@mcp-abap-adt/connection 1.0.0 → 1.1.0

package/README.md

@@ -7,6 +7,7 @@ ABAP connection layer for MCP ABAP ADT server. Provides a unified interface for
 - 🔐 **Multiple Authentication Methods**: 
   - Basic Auth for on-premise SAP systems
   - JWT/OAuth2 for SAP BTP ABAP Environment
+  - SAML session cookies for pre-authenticated enterprise flows
 - 🔄 **Token Management**: 
   - Token refresh is handled by `@mcp-abap-adt/auth-broker` package
   - Connection package focuses on HTTP communication only
@@ -15,8 +16,11 @@ ABAP connection layer for MCP ABAP ADT server. Provides a unified interface for
   - Session state persistence is handled by `@mcp-abap-adt/auth-broker` package
 - 🏗️ **Clean Architecture**:
   - Abstract base class for common HTTP/session logic
-  - Auth-type specific implementations (BaseAbapConnection, JwtAbapConnection)
+  - Auth-type specific implementations (BaseAbapConnection, JwtAbapConnection, SamlAbapConnection)
   - Proper separation of concerns - no JWT logic in base class
+- 🔌 **Realtime Transport Scaffold**:
+  - Generic `GenericWebSocketTransport` with pluggable WS factory
+  - Reusable for debugger/traces and other event-driven flows
 - 📝 **Custom Logging**: Pluggable logger interface for integration with any logging system
 - 🛠️ **CLI Tool**: See [JWT Auth Tools](./docs/JWT_AUTH_TOOLS.md) for obtaining SAP BTP tokens
 - 📦 **TypeScript**: Full TypeScript support with type definitions included
@@ -43,6 +47,16 @@ The package uses a clean separation of concerns:
   - Suitable for SAP BTP ABAP Environment
   - Token refresh handled by auth-broker package
 
+- **`SamlAbapConnection`** (concrete, exported):
+  - Session-cookie-based authentication (`authType: "saml"`)
+  - Uses existing SSO/SAML session cookies
+  - Fetches CSRF token and executes ADT requests in same HTTP model
+
+- **`GenericWebSocketTransport`** (concrete, exported):
+  - Transport abstraction for realtime WS message flows
+  - Pluggable factory, envelope-based send/receive
+  - Intended for higher-level debugger/trace session orchestration
+
 ## Responsibilities and Design Principles
 
 ### Core Development Principle

package/dist/connection/GenericWebSocketTransport.d.ts

@@ -0,0 +1,46 @@
+import type { IWebSocketCloseInfo, IWebSocketConnectOptions, IWebSocketMessageEnvelope, IWebSocketMessageHandler, IWebSocketTransport } from '@mcp-abap-adt/interfaces';
+/**
+ * Minimal WS-like instance contract to avoid hard dependency on a specific WS library.
+ */
+interface IWebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+        wasClean?: boolean;
+    }) => void) | null;
+}
+interface IWebSocketFactory {
+    create(url: string, protocols?: string | string[], options?: IWebSocketConnectOptions): IWebSocketLike;
+}
+export declare class GenericWebSocketTransport implements IWebSocketTransport {
+    private readonly factory;
+    private socket;
+    private messageHandlers;
+    private openHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    constructor(factory: IWebSocketFactory);
+    connect(url: string, options?: IWebSocketConnectOptions): Promise<void>;
+    disconnect(code?: number, reason?: string): Promise<void>;
+    send<T = unknown>(message: IWebSocketMessageEnvelope<T>): Promise<void>;
+    onMessage<T = unknown>(handler: IWebSocketMessageHandler<T>): void;
+    onOpen(handler: () => void | Promise<void>): void;
+    onError(handler: (error: Error) => void | Promise<void>): void;
+    onClose(handler: (info: IWebSocketCloseInfo) => void | Promise<void>): void;
+    isConnected(): boolean;
+    private handleIncomingMessage;
+    private normalizeError;
+    private emitOpen;
+    private emitError;
+    private emitClose;
+}
+export type { IWebSocketFactory, IWebSocketLike };
+//# sourceMappingURL=GenericWebSocketTransport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GenericWebSocketTransport.d.ts","sourceRoot":"","sources":["../../src/connection/GenericWebSocketTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC;;GAEG;AACH,UAAU,cAAc;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACvD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,OAAO,EACH,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GACzE,IAAI,CAAC;CACV;AAED,UAAU,iBAAiB;IACzB,MAAM,CACJ,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,EAC7B,OAAO,CAAC,EAAE,wBAAwB,GACjC,cAAc,CAAC;CACnB;AAID,qBAAa,yBAA0B,YAAW,mBAAmB;IASvD,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,eAAe,CAAgD;IACvE,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,aAAa,CAAqD;IAC1E,OAAO,CAAC,aAAa,CAEd;gBAEsB,OAAO,EAAE,iBAAiB;IAEjD,OAAO,CACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,IAAI,CAAC;IAqDV,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBzD,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC;IAQhB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIlE,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAIjD,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI9D,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAI3E,WAAW,IAAI,OAAO;YAIR,qBAAqB;IAoBnC,OAAO,CAAC,cAAc;YAUR,QAAQ;YAMR,SAAS;YAMT,SAAS;CAKxB;AAED,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC"}

package/dist/connection/GenericWebSocketTransport.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericWebSocketTransport = void 0;
+const WS_OPEN = 1;
+class GenericWebSocketTransport {
+    factory;
+    socket = null;
+    messageHandlers = [];
+    openHandlers = [];
+    errorHandlers = [];
+    closeHandlers = [];
+    constructor(factory) {
+        this.factory = factory;
+    }
+    async connect(url, options) {
+        if (this.socket && this.isConnected()) {
+            return;
+        }
+        const connectTimeoutMs = options?.connectTimeoutMs ?? 15000;
+        const socket = this.factory.create(url, options?.protocols, options);
+        this.socket = socket;
+        await new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`WebSocket connect timeout after ${connectTimeoutMs}ms`));
+            }, connectTimeoutMs);
+            socket.onopen = () => {
+                clearTimeout(timeoutId);
+                this.emitOpen().catch(() => {
+                    // no-op
+                });
+                resolve();
+            };
+            socket.onerror = (event) => {
+                clearTimeout(timeoutId);
+                const err = this.normalizeError(event, 'WebSocket connection error');
+                this.emitError(err).catch(() => {
+                    // no-op
+                });
+                reject(err);
+            };
+            socket.onclose = (event) => {
+                clearTimeout(timeoutId);
+                const info = {
+                    code: typeof event?.code === 'number' ? event.code : 1006,
+                    reason: event?.reason,
+                    wasClean: event?.wasClean,
+                };
+                this.emitClose(info).catch(() => {
+                    // no-op
+                });
+            };
+            socket.onmessage = (event) => {
+                this.handleIncomingMessage(event?.data).catch(() => {
+                    // no-op
+                });
+            };
+        });
+    }
+    async disconnect(code, reason) {
+        if (!this.socket) {
+            return;
+        }
+        const socket = this.socket;
+        this.socket = null;
+        try {
+            socket.close(code, reason);
+        }
+        catch (error) {
+            const err = this.normalizeError(error, 'WebSocket close failed');
+            await this.emitError(err);
+        }
+    }
+    async send(message) {
+        if (!this.socket || this.socket.readyState !== WS_OPEN) {
+            throw new Error('WebSocket is not connected');
+        }
+        this.socket.send(JSON.stringify(message));
+    }
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    onOpen(handler) {
+        this.openHandlers.push(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.push(handler);
+    }
+    onClose(handler) {
+        this.closeHandlers.push(handler);
+    }
+    isConnected() {
+        return !!this.socket && this.socket.readyState === WS_OPEN;
+    }
+    async handleIncomingMessage(rawData) {
+        try {
+            const text = typeof rawData === 'string'
+                ? rawData
+                : rawData instanceof Buffer
+                    ? rawData.toString('utf8')
+                    : String(rawData ?? '');
+            const parsed = JSON.parse(text);
+            for (const handler of this.messageHandlers) {
+                await handler(parsed);
+            }
+        }
+        catch (error) {
+            await this.emitError(this.normalizeError(error, 'Failed to process WS message'));
+        }
+    }
+    normalizeError(error, fallback) {
+        if (error instanceof Error) {
+            return error;
+        }
+        if (typeof error === 'string' && error.trim()) {
+            return new Error(error.trim());
+        }
+        return new Error(fallback);
+    }
+    async emitOpen() {
+        for (const handler of this.openHandlers) {
+            await handler();
+        }
+    }
+    async emitError(error) {
+        for (const handler of this.errorHandlers) {
+            await handler(error);
+        }
+    }
+    async emitClose(info) {
+        for (const handler of this.closeHandlers) {
+            await handler(info);
+        }
+    }
+}
+exports.GenericWebSocketTransport = GenericWebSocketTransport;

package/dist/index.d.ts

@@ -1,9 +1,11 @@
+export type { IWebSocketCloseInfo, IWebSocketConnectOptions, IWebSocketMessageEnvelope, IWebSocketMessageHandler, IWebSocketTransport, } from '@mcp-abap-adt/interfaces';
 export type { SapAuthType, SapConfig, } from './config/sapConfig.js';
 export { sapConfigSignature } from './config/sapConfig.js';
 export type { AbapConnection, AbapRequestOptions, } from './connection/AbapConnection.js';
 export { BaseAbapConnection, BaseAbapConnection as OnPremAbapConnection, } from './connection/BaseAbapConnection.js';
 export { createAbapConnection } from './connection/connectionFactory.js';
 export { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from './connection/csrfConfig.js';
+export { GenericWebSocketTransport, type IWebSocketFactory, type IWebSocketLike, } from './connection/GenericWebSocketTransport.js';
 export { JwtAbapConnection, JwtAbapConnection as CloudAbapConnection, } from './connection/JwtAbapConnection.js';
 export { SamlAbapConnection } from './connection/SamlAbapConnection.js';
 export type { ILogger } from './logger.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,SAAS,GACV,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,YAAY,EACV,cAAc,EACd,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,IAAI,oBAAoB,GAC3C,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EACL,iBAAiB,EACjB,iBAAiB,IAAI,mBAAmB,GACzC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,WAAW,EACX,SAAS,GACV,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,YAAY,EACV,cAAc,EACd,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,IAAI,oBAAoB,GAC3C,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EACL,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,IAAI,mBAAmB,GACzC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
+// Types - re-exported from interfaces package with backward compatibility aliases
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTimeoutConfig = exports.getTimeout = exports.SamlAbapConnection = exports.CloudAbapConnection = exports.JwtAbapConnection = exports.CSRF_ERROR_MESSAGES = exports.CSRF_CONFIG = exports.createAbapConnection = exports.OnPremAbapConnection = exports.BaseAbapConnection = exports.sapConfigSignature = void 0;
+exports.getTimeoutConfig = exports.getTimeout = exports.SamlAbapConnection = exports.CloudAbapConnection = exports.JwtAbapConnection = exports.GenericWebSocketTransport = exports.CSRF_ERROR_MESSAGES = exports.CSRF_CONFIG = exports.createAbapConnection = exports.OnPremAbapConnection = exports.BaseAbapConnection = exports.sapConfigSignature = void 0;
 // Config utilities
 var sapConfig_js_1 = require("./config/sapConfig.js");
 Object.defineProperty(exports, "sapConfigSignature", { enumerable: true, get: function () { return sapConfig_js_1.sapConfigSignature; } });
@@ -16,6 +17,8 @@ Object.defineProperty(exports, "createAbapConnection", { enumerable: true, get:
 var csrfConfig_js_1 = require("./connection/csrfConfig.js");
 Object.defineProperty(exports, "CSRF_CONFIG", { enumerable: true, get: function () { return csrfConfig_js_1.CSRF_CONFIG; } });
 Object.defineProperty(exports, "CSRF_ERROR_MESSAGES", { enumerable: true, get: function () { return csrfConfig_js_1.CSRF_ERROR_MESSAGES; } });
+var GenericWebSocketTransport_js_1 = require("./connection/GenericWebSocketTransport.js");
+Object.defineProperty(exports, "GenericWebSocketTransport", { enumerable: true, get: function () { return GenericWebSocketTransport_js_1.GenericWebSocketTransport; } });
 var JwtAbapConnection_js_1 = require("./connection/JwtAbapConnection.js");
 Object.defineProperty(exports, "JwtAbapConnection", { enumerable: true, get: function () { return JwtAbapConnection_js_1.JwtAbapConnection; } });
 Object.defineProperty(exports, "CloudAbapConnection", { enumerable: true, get: function () { return JwtAbapConnection_js_1.JwtAbapConnection; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,16 +46,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@mcp-abap-adt/interfaces": "^2.3.0",
-    "axios": "^1.11.0",
-    "commander": "^14.0.2",
+    "@mcp-abap-adt/interfaces": "^2.4.0",
+    "axios": "^1.13.5",
+    "commander": "^14.0.3",
     "express": "^5.1.0",
     "open": "^11.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
+    "@biomejs/biome": "^2.3.14",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.2.1",
+    "@types/node": "^25.2.3",
     "jest": "^30.2.0",
     "jest-util": "^30.2.0",
     "ts-jest": "^29.2.5",