@mcp-abap-adt/connection 1.10.2 → 2.0.0

package/examples/README.md

@@ -0,0 +1,112 @@
+# Connection Examples
+
+This directory contains example code demonstrating how to use the `@mcp-abap-adt/connection` package.
+
+## Prerequisites
+
+```bash
+# Install dependencies
+cd packages/connection
+npm install
+
+# Build the package
+npm run build
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your SAP credentials
+```
+
+## Available Examples
+
+### basic-connection.js
+
+Simple example showing how to connect to SAP and make an ADT request.
+
+```bash
+node examples/basic-connection.js
+```
+
+**What it demonstrates:**
+- Creating connection with factory function
+- Connecting to SAP system
+- Making GET request to ADT endpoint
+- Basic error handling
+
+### jwt-with-token-refresh.js
+
+Shows how to use `ITokenRefresher` for automatic token refresh.
+
+```bash
+node examples/jwt-with-token-refresh.js
+```
+
+**What it demonstrates:**
+- Creating connection with token refresher injection
+- Automatic token refresh on 401/403 errors
+- Retry logic with refreshed token
+
+### saml-connection.js
+
+Shows how to use cookie-based SAML connection.
+
+```bash
+node examples/saml-connection.js
+```
+
+**What it demonstrates:**
+- Creating SAML connection via factory (`authType: "saml"`)
+- Using `sessionCookies` from environment
+- Fetching CSRF token and making ADT request with cookie auth
+
+### websocket-transport.js
+
+Shows how to use `GenericWebSocketTransport` with injected WS factory.
+
+```bash
+node examples/websocket-transport.js
+```
+
+**What it demonstrates:**
+- Creating `GenericWebSocketTransport`
+- Registering `onOpen`, `onMessage`, `onError`, `onClose` handlers
+- Sending `IWebSocketMessageEnvelope` payload
+- Connecting/disconnecting transport lifecycle
+
+## Configuration
+
+### Using .env file
+
+Create `.env` in project root:
+
+```bash
+# Basic Auth
+SAP_URL=https://your-sap-system.com
+SAP_AUTH_TYPE=basic
+SAP_USERNAME=your_username
+SAP_PASSWORD=your_password
+SAP_CLIENT=100
+
+# JWT Auth (Cloud/BTP)
+SAP_AUTH_TYPE=jwt
+SAP_JWT_TOKEN=eyJhbGciOiJSUzI1NiIs...
+# Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
+
+# SAML Auth (Cookie-based)
+SAP_AUTH_TYPE=saml
+SAP_SESSION_COOKIES=sap-usercontext=sap-client=100; sap-contextid=...
+```
+
+### Using Environment Variables
+
+```bash
+export SAP_URL=https://your-sap-system.com
+export SAP_USERNAME=your_username
+export SAP_PASSWORD=your_password
+node examples/basic-connection.js
+```
+
+## See Also
+
+- [Connection README](../README.md) - Main package documentation
+- [Session Lifecycle](../docs/USAGE.md#session-lifecycle) - connect/disconnect, lock windows, a lost session

package/examples/basic-connection.js

@@ -0,0 +1,55 @@
+/**
+ * Basic Connection Example
+ *
+ * Demonstrates simple connection to SAP system and making ADT request
+ */
+
+const { createAbapConnection } = require('@mcp-abap-adt/connection');
+
+async function main() {
+  // Configuration from environment or hardcoded
+  const config = {
+    url: process.env.SAP_URL || 'https://your-sap-server.com',
+    authType: process.env.SAP_AUTH_TYPE || 'basic',
+    username: process.env.SAP_USERNAME,
+    password: process.env.SAP_PASSWORD,
+    client: process.env.SAP_CLIENT || '100',
+  };
+
+  console.log('Creating connection to', config.url);
+
+  // Create connection (factory auto-detects cloud vs on-premise)
+  const connection = createAbapConnection(config, console);
+
+  try {
+    // Connect and get CSRF token
+    console.log('Connecting to SAP system...');
+    await connection.connect();
+    console.log('✓ Connected successfully');
+
+    // Make a simple ADT request
+    console.log('\nFetching repository structure...');
+    const response = await connection.makeAdtRequest({
+      method: 'GET',
+      url: '/sap/bc/adt/repository/nodestructure',
+      params: {
+        parent_name: 'DEVC/K',
+        parent_type: 'DEVC/K',
+        withShortDescriptions: 'true',
+      },
+    });
+
+    console.log('✓ Request successful');
+    console.log('Response status:', response.status);
+    console.log('Data length:', response.data.length);
+  } catch (error) {
+    console.error('✗ Error:', error.message);
+    if (error.response) {
+      console.error('  Status:', error.response.status);
+      console.error('  Data:', error.response.data);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/examples/jwt-with-token-refresh.js

@@ -0,0 +1,87 @@
+/**
+ * Example: JWT Connection with Automatic Token Refresh
+ *
+ * This example demonstrates how to create a JwtAbapConnection with
+ * automatic token refresh using ITokenRefresher from auth-broker.
+ *
+ * When 401/403 errors occur, the connection automatically:
+ * 1. Calls tokenRefresher.refreshToken() to get a new token
+ * 2. Updates internal token state
+ * 3. Retries the failed request with the new token
+ */
+
+const { JwtAbapConnection } = require('@mcp-abap-adt/connection');
+// const { AuthBroker } = require('@mcp-abap-adt/auth-broker');
+
+// Simple logger
+const logger = {
+  info: (msg, meta) => console.log('[INFO]', msg, meta || ''),
+  error: (msg, meta) => console.error('[ERROR]', msg, meta || ''),
+  warn: (msg, meta) => console.warn('[WARN]', msg, meta || ''),
+  debug: (msg, meta) => console.debug('[DEBUG]', msg, meta || ''),
+};
+
+async function main() {
+  // Option 1: Using AuthBroker (recommended for production)
+  // const broker = new AuthBroker({
+  //   sessionStore: mySessionStore,
+  //   serviceKeyStore: myServiceKeyStore,
+  //   tokenProvider: myTokenProvider,
+  // });
+  // const tokenRefresher = broker.createTokenRefresher('TRIAL');
+  // const initialToken = await tokenRefresher.getToken();
+
+  // Option 2: Manual ITokenRefresher implementation (for testing/custom scenarios)
+  const tokenRefresher = {
+    getToken: async () => {
+      console.log('getToken called - returning cached or refreshed token');
+      return process.env.SAP_JWT_TOKEN || 'your-jwt-token';
+    },
+    refreshToken: async () => {
+      console.log('refreshToken called - forcing token refresh');
+      // In real implementation: call OAuth2 token endpoint
+      // Save new token to session store
+      // Return new token
+      return 'newly-refreshed-jwt-token';
+    },
+  };
+
+  // Get initial token
+  const initialToken = await tokenRefresher.getToken();
+
+  // JWT configuration
+  const config = {
+    url: process.env.SAP_URL || 'https://your-instance.abap.cloud.sap',
+    authType: 'jwt',
+    jwtToken: initialToken,
+  };
+
+  // Create connection with token refresher
+  // 4th parameter is the ITokenRefresher
+  const connection = new JwtAbapConnection(
+    config,
+    logger,
+    undefined,
+    tokenRefresher,
+  );
+
+  try {
+    await connection.connect();
+
+    // This request will automatically refresh token if 401/403 occurs. Note
+    // that a refresh replaces the SAP session: with a lock window open the
+    // request would fail with ADT_SESSION_REPLACED rather than continue on a
+    // session your lock is not in.
+    const response = await connection.makeAdtRequest({
+      method: 'GET',
+      url: '/sap/bc/adt/discovery',
+    });
+
+    console.log('Request succeeded:', response.status);
+    console.log('Discovery data available');
+  } catch (error) {
+    console.error('Request failed:', error.message);
+  }
+}
+
+main().catch(console.error);

package/examples/saml-connection.js

@@ -0,0 +1,52 @@
+/**
+ * SAML Connection Example
+ *
+ * Demonstrates using cookie-based SAML authentication.
+ * Session cookies are expected from prior login flow.
+ */
+
+const { createAbapConnection } = require('@mcp-abap-adt/connection');
+
+async function main() {
+  const config = {
+    url: process.env.SAP_URL || 'https://your-sap-server.com',
+    authType: 'saml',
+    sessionCookies: process.env.SAP_SESSION_COOKIES,
+    client: process.env.SAP_CLIENT || '100',
+  };
+
+  if (!config.sessionCookies) {
+    throw new Error(
+      'SAP_SESSION_COOKIES is required for SAML example (full Cookie header value)',
+    );
+  }
+
+  console.log('Creating SAML connection to', config.url);
+  const connection = createAbapConnection(config, console);
+
+  try {
+    console.log('Connecting using session cookies...');
+    await connection.connect();
+    console.log('✓ Connected successfully');
+
+    const response = await connection.makeAdtRequest({
+      method: 'GET',
+      url: '/sap/bc/adt/discovery',
+    });
+
+    console.log('✓ Request successful');
+    console.log('Response status:', response.status);
+  } catch (error) {
+    console.error('✗ Error:', error.message || String(error));
+    if (error.response) {
+      console.error('  Status:', error.response.status);
+      console.error('  Data:', error.response.data);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Fatal:', error.message || String(error));
+  process.exit(1);
+});

package/examples/websocket-transport.js

@@ -0,0 +1,87 @@
+/**
+ * Generic WebSocket Transport Example
+ *
+ * Demonstrates how to plug a concrete WebSocket implementation
+ * into GenericWebSocketTransport through the factory interface.
+ */
+
+const { GenericWebSocketTransport } = require('@mcp-abap-adt/connection');
+
+class MockWebSocket {
+  constructor() {
+    this.readyState = 0;
+    this.onopen = null;
+    this.onmessage = null;
+    this.onerror = null;
+    this.onclose = null;
+
+    setTimeout(() => {
+      this.readyState = 1;
+      if (this.onopen) this.onopen({});
+    }, 10);
+  }
+
+  send(payload) {
+    // Echo payload back as "event" for demo purposes.
+    if (this.onmessage) {
+      this.onmessage({ data: payload });
+    }
+  }
+
+  close(code, reason) {
+    this.readyState = 3;
+    if (this.onclose) {
+      this.onclose({
+        code: code || 1000,
+        reason: reason || 'normal',
+        wasClean: true,
+      });
+    }
+  }
+}
+
+const mockFactory = {
+  create(_url, _protocols, _options) {
+    return new MockWebSocket();
+  },
+};
+
+async function main() {
+  const transport = new GenericWebSocketTransport(mockFactory);
+
+  transport.onOpen(() => {
+    console.log('✓ WS open');
+  });
+
+  transport.onMessage((message) => {
+    console.log('message:', message);
+  });
+
+  transport.onError((error) => {
+    console.error('error:', error.message);
+  });
+
+  transport.onClose((info) => {
+    console.log('closed:', info);
+  });
+
+  await transport.connect('wss://example.invalid/realtime', {
+    connectTimeoutMs: 5000,
+    heartbeatIntervalMs: 30000,
+  });
+
+  await transport.send({
+    kind: 'request',
+    correlationId: 'demo-1',
+    operation: 'debugger.listen',
+    payload: { timeoutSeconds: 30 },
+    timestamp: Date.now(),
+  });
+
+  await transport.disconnect(1000, 'demo finished');
+}
+
+main().catch((error) => {
+  console.error('Fatal:', error.message || String(error));
+  process.exit(1);
+});

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "1.10.2",
+  "version": "2.0.0",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
     "bin",
+    "docs",
+    "examples",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "bin": {
@@ -39,14 +42,15 @@
     "format": "npx biome format --write src",
     "build": "npm run --silent clean && npx biome check src --diagnostic-level=error && npx tsc -p tsconfig.json",
     "build:fast": "npx tsc -p tsconfig.json",
-    "test": "jest",
-    "prepublishOnly": "npm run build"
+    "test": "npm run --silent check:docs && jest",
+    "prepublishOnly": "npm run build && npm run check:docs",
+    "check:docs": "node scripts/check-docs.mjs"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@mcp-abap-adt/interfaces": "^7.2.0",
+    "@mcp-abap-adt/interfaces": "^11.5.0",
     "axios": "^1.16.0",
     "commander": "^14.0.3",
     "express": "^5.1.0",
@@ -65,5 +69,8 @@
     "jest-util": "^30.2.0",
     "ts-jest": "^29.2.5",
     "typescript": "^5.9.2"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.8"
   }
 }