@mcp-abap-adt/interfaces 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-02-14
+
+### Added
+- Added execution contract interface:
+  - `IExecutor<TTarget, TResult, TRunWithProfilerOptions, TRunWithProfilingOptions, TRunWithProfilingResult>`
+- Exported `IExecutor` from package root (`@mcp-abap-adt/interfaces`).
+
+## [2.4.0] - 2026-02-13
+
+### Added
+- Added generic realtime WebSocket transport contracts in connection domain:
+  - `IWebSocketTransport`
+  - `IWebSocketConnectOptions`
+  - `IWebSocketCloseInfo`
+  - `IWebSocketMessageEnvelope`
+  - `IWebSocketMessageHandler`
+- Exported all new WebSocket contracts from package root.
+
 ## [2.3.0] - 2026-02-10
 
 ### Added

package/README.md

@@ -19,7 +19,8 @@ This package contains all interfaces organized by domain:
 - **`token/`** - Token-related interfaces (token provider, results, options)
 - **`session/`** - Session storage interface
 - **`serviceKey/`** - Service key storage interface
-- **`connection/`** - Connection interfaces (AbapConnection, request options)
+- **`connection/`** - Connection and realtime transport interfaces (AbapConnection, request options, WebSocket transport contracts)
+- **`execution/`** - Execution contracts for runnable entities (`IExecutor`)
 - **`sap/`** - SAP-specific configuration (SapConfig, SapAuthType)
 - **`storage/`** - Storage interfaces (session storage, state)
 - **`logging/`** - Logging interfaces (ILogger, LogLevel enum)
@@ -44,6 +45,9 @@ import {
   IServiceKeyStore,
   ITokenProvider,
   IAbapConnection,
+  IExecutor,
+  IWebSocketTransport,
+  IWebSocketMessageEnvelope,
   ISapConfig,
   ILogger,
   TOKEN_PROVIDER_ERROR_CODES,
@@ -185,11 +189,23 @@ This package is responsible for:
   - For JWT: token refresh handled internally via `ITokenRefresher`
   - For Basic: no token refresh needed
 - `IAdtResponse` - Minimal response shape returned by `makeAdtRequest()`
+- `IWebSocketTransport` - Generic realtime transport contract for WS-based flows
+  - Methods: `connect()`, `disconnect()`, `send()`, `onMessage()`, `onOpen()`, `onError()`, `onClose()`, `isConnected()`
+- `IWebSocketConnectOptions` - WS connect options (`protocols`, `headers`, timeouts, heartbeat)
+- `IWebSocketMessageEnvelope` - Generic request/response/event/error message shape with correlation id
+- `IWebSocketCloseInfo` / `IWebSocketMessageHandler` - Close payload and message callback contracts
 - `IAbapConnectionExtended` - Deprecated, for backward compatibility
   - Extends `IAbapConnection` with: `getConfig()`, `getAuthHeaders()`, `connect()`, `reset()`
   - Will be removed in next major version
 - `IAbapRequestOptions` - Request options for ADT operations
 
+### Execution Domain (`execution/`)
+- `IExecutor<TTarget, TResult, TRunWithProfilerOptions, TRunWithProfilingOptions, TRunWithProfilingResult>`
+  - Generic contract for entities that support:
+    - `run(target)`
+    - `runWithProfiler(target, options)`
+    - `runWithProfiling(target, options?)`
+
 ### SAP Domain (`sap/`)
 - `ISapConfig` - SAP connection configuration
 - `SapAuthType` - Authentication type: `"basic" | "jwt"`

package/dist/connection/IWebSocketTransport.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Generic WebSocket transport contracts.
+ *
+ * This interface is intentionally domain-agnostic and can be reused by
+ * debugger, tracing, and any other realtime ADT flows.
+ */
+export interface IWebSocketConnectOptions {
+    /**
+     * Optional subprotocols for the WS handshake.
+     */
+    protocols?: string[];
+    /**
+     * Request headers used during connection handshake.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Connection timeout in milliseconds.
+     */
+    connectTimeoutMs?: number;
+    /**
+     * Optional heartbeat interval in milliseconds.
+     */
+    heartbeatIntervalMs?: number;
+}
+export interface IWebSocketCloseInfo {
+    code: number;
+    reason?: string;
+    wasClean?: boolean;
+}
+export interface IWebSocketMessageEnvelope<T = unknown> {
+    /**
+     * Message category. Keep generic to support different realtime domains.
+     */
+    kind: 'request' | 'response' | 'event' | 'error';
+    /**
+     * Optional correlation id for request/response matching.
+     */
+    correlationId?: string;
+    /**
+     * Optional operation name (for example: "debugger.listen", "trace.stream").
+     */
+    operation?: string;
+    /**
+     * Message payload.
+     */
+    payload?: T;
+    /**
+     * Unix timestamp in milliseconds.
+     */
+    timestamp?: number;
+}
+export type IWebSocketMessageHandler<T = unknown> = (message: IWebSocketMessageEnvelope<T>) => void | Promise<void>;
+export interface IWebSocketTransport {
+    /**
+     * Establish WS connection.
+     */
+    connect(url: string, options?: IWebSocketConnectOptions): Promise<void>;
+    /**
+     * Close WS connection.
+     */
+    disconnect(code?: number, reason?: string): Promise<void>;
+    /**
+     * Send one message to the connected endpoint.
+     */
+    send<T = unknown>(message: IWebSocketMessageEnvelope<T>): Promise<void>;
+    /**
+     * Register message handler.
+     */
+    onMessage<T = unknown>(handler: IWebSocketMessageHandler<T>): void;
+    /**
+     * Register one-shot or persistent open callback.
+     */
+    onOpen(handler: () => void | Promise<void>): void;
+    /**
+     * Register error callback.
+     */
+    onError(handler: (error: Error) => void | Promise<void>): void;
+    /**
+     * Register close callback.
+     */
+    onClose(handler: (info: IWebSocketCloseInfo) => void | Promise<void>): void;
+    /**
+     * Transport state indicator.
+     */
+    isConnected(): boolean;
+}
+//# sourceMappingURL=IWebSocketTransport.d.ts.map

package/dist/connection/IWebSocketTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IWebSocketTransport.d.ts","sourceRoot":"","sources":["../../src/connection/IWebSocketTransport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,OAAO;IACpD;;OAEG;IACH,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;IAEjD;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;IAEZ;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,OAAO,IAAI,CAClD,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,KAClC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;OAEG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;OAEG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;OAEG;IACH,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEnE;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAElD;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE/D;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE5E;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;CACxB"}

package/dist/connection/IWebSocketTransport.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Generic WebSocket transport contracts.
+ *
+ * This interface is intentionally domain-agnostic and can be reused by
+ * debugger, tracing, and any other realtime ADT flows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/execution/IExecutor.d.ts

@@ -0,0 +1,10 @@
+import type { IAdtResponse } from '../connection/IAbapConnection';
+/**
+ * Generic execution contract for executable ADT entities.
+ */
+export interface IExecutor<TTarget, TResult = IAdtResponse, TRunWithProfilerOptions = unknown, TRunWithProfilingOptions = unknown, TRunWithProfilingResult = unknown> {
+    run(target: TTarget): Promise<TResult>;
+    runWithProfiler(target: TTarget, options: TRunWithProfilerOptions): Promise<TResult>;
+    runWithProfiling(target: TTarget, options?: TRunWithProfilingOptions): Promise<TRunWithProfilingResult>;
+}
+//# sourceMappingURL=IExecutor.d.ts.map

package/dist/execution/IExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IExecutor.d.ts","sourceRoot":"","sources":["../../src/execution/IExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,SAAS,CACxB,OAAO,EACP,OAAO,GAAG,YAAY,EACtB,uBAAuB,GAAG,OAAO,EACjC,wBAAwB,GAAG,OAAO,EAClC,uBAAuB,GAAG,OAAO;IAEjC,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,eAAe,CACb,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,gBAAgB,CACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACrC"}

package/dist/execution/IExecutor.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -13,8 +13,10 @@ export type { IConfig } from './auth/IConfig';
 export type { IConnectionConfig } from './auth/IConnectionConfig';
 export type { IAbapConnection, IAdtResponse, } from './connection/IAbapConnection';
 export type { IAbapRequestOptions } from './connection/IAbapRequestOptions';
+export type { IWebSocketCloseInfo, IWebSocketConnectOptions, IWebSocketMessageEnvelope, IWebSocketMessageHandler, IWebSocketTransport, } from './connection/IWebSocketTransport';
 export type { NetworkErrorCode } from './connection/NetworkErrors';
 export { isNetworkError, NETWORK_ERROR_CODES, } from './connection/NetworkErrors';
+export type { IExecutor } from './execution/IExecutor';
 export * from './Headers';
 export type { ILogger } from './logging/ILogger';
 export { LogLevel } from './logging/LogLevel';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/E,YAAY,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhE,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,YAAY,EACV,eAAe,EACf,YAAY,GACb,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,cAAc,EACd,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AAEpC,cAAc,WAAW,CAAC;AAE1B,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EACL,4BAA4B,EAC5B,iCAAiC,EACjC,4BAA4B,EAC5B,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAEpF,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/E,YAAY,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhE,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,YAAY,EACV,eAAe,EACf,YAAY,GACb,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,cAAc,EACd,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,cAAc,WAAW,CAAC;AAE1B,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EACL,4BAA4B,EAC5B,iCAAiC,EACjC,4BAA4B,EAC5B,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAEpF,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/interfaces",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Shared interfaces for MCP ABAP ADT packages",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",