@mcp-abap-adt/connection 1.10.2 → 3.0.0

package/docs/INSTALLATION.md

@@ -0,0 +1,304 @@
+# Installation Guide
+
+**Version:** see [CHANGELOG.md](../CHANGELOG.md)  
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn package manager
+- Access to SAP ABAP system (on-premise or BTP)
+
+## Installation
+
+### As NPM Package (Recommended)
+
+```bash
+npm install @mcp-abap-adt/connection
+```
+
+### With Yarn
+
+```bash
+yarn add @mcp-abap-adt/connection
+```
+
+### From Source
+
+```bash
+git clone https://github.com/fr0ster/mcp-abap-connection.git
+cd mcp-abap-connection
+npm install
+npm run build
+```
+
+## Environment Setup
+
+### Basic Authentication (On-Premise)
+
+Create a `.env` file in your project root:
+
+```bash
+SAP_URL=https://your-sap-server.com:8000
+SAP_CLIENT=100
+SAP_AUTH_TYPE=basic
+SAP_USERNAME=your-username
+SAP_PASSWORD=your-password
+```
+
+### JWT Authentication (SAP BTP Cloud)
+
+When using the `sap-abap-auth` CLI tool, the generated `.env` file will include token expiry information:
+
+```bash
+# Token Expiry Information (auto-generated)
+# JWT Token expires: Monday, December 25, 2025 at 10:30:45 AM UTC
+# JWT Token expires at: 2025-12-25T10:30:45.000Z
+# Refresh Token expires: Tuesday, January 25, 2026 at 10:30:45 AM UTC
+# Refresh Token expires at: 2026-01-25T10:30:45.000Z
+
+SAP_URL=https://your-instance.abap.cloud.sap
+SAP_CLIENT=100
+SAP_AUTH_TYPE=jwt
+SAP_JWT_TOKEN=your-jwt-token
+
+# Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
+# Connection package does not use refresh token credentials
+```
+
+**Manual Setup:** If creating `.env` manually (without CLI), you can omit the expiry comments:
+
+```bash
+SAP_URL=https://your-instance.abap.cloud.sap
+SAP_CLIENT=100
+SAP_AUTH_TYPE=jwt
+SAP_JWT_TOKEN=your-jwt-token
+
+# Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
+# Connection package does not use refresh token credentials
+```
+
+### Loading Environment Variables
+
+In your code:
+
+```typescript
+import 'dotenv/config'; // or require('dotenv').config();
+import { createAbapConnection } from '@mcp-abap-adt/connection';
+
+const config = {
+  url: process.env.SAP_URL!,
+  client: process.env.SAP_CLIENT,
+  authType: process.env.SAP_AUTH_TYPE as 'basic' | 'jwt',
+  username: process.env.SAP_USERNAME,
+  password: process.env.SAP_PASSWORD,
+  jwtToken: process.env.SAP_JWT_TOKEN,
+  // Note: Token refresh credentials are not used by connection package
+  // Token refresh is handled by @mcp-abap-adt/auth-broker
+};
+```
+
+## CLI Tool Installation
+
+The package includes `sap-abap-auth` CLI tool for browser-based JWT authentication.
+
+### Global Installation
+
+```bash
+npm install -g @mcp-abap-adt/connection
+```
+
+Then use directly:
+
+```bash
+sap-abap-auth auth -k service-key.json
+```
+
+### Local Project Installation
+
+```bash
+npm install --save-dev @mcp-abap-adt/connection
+```
+
+Use via npx:
+
+```bash
+npx sap-abap-auth auth -k service-key.json
+```
+
+### On-Demand (No Installation)
+
+```bash
+npx @mcp-abap-adt/connection sap-abap-auth auth -k service-key.json
+```
+
+See [JWT_AUTH_TOOLS.md](./JWT_AUTH_TOOLS.md) for detailed CLI documentation.
+
+## Verification
+
+### Test Installation
+
+```bash
+node -e "const { createAbapConnection } = require('@mcp-abap-adt/connection'); console.log('✓ Package loaded successfully');"
+```
+
+### Test Connection (Basic Auth)
+
+Create `test-connection.js`:
+
+```javascript
+const { createAbapConnection } = require('@mcp-abap-adt/connection');
+
+const config = {
+  url: 'https://your-sap-server.com',
+  authType: 'basic',
+  username: 'your-username',
+  password: 'your-password',
+  client: '100'
+};
+
+const logger = {
+  info: (msg) => console.log('[INFO]', msg),
+  error: (msg) => console.error('[ERROR]', msg),
+  warn: (msg) => console.warn('[WARN]', msg),
+  debug: (msg) => console.log('[DEBUG]', msg),
+};
+
+const connection = createAbapConnection(config, logger);
+
+connection.connect()
+  .then(() =>
+    connection.makeAdtRequest({
+      method: 'GET',
+      url: '/sap/bc/adt/discovery',
+    }),
+  )
+  .then(() => console.log('✓ Connection successful'))
+  .catch((err) => console.error('✗ Connection failed:', err.message));
+```
+
+Run:
+
+```bash
+node test-connection.js
+```
+
+## TypeScript Setup
+
+### Install TypeScript
+
+```bash
+npm install --save-dev typescript @types/node
+```
+
+### Create `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### TypeScript Example
+
+```typescript
+import { createAbapConnection, SapConfig, ILogger } from '@mcp-abap-adt/connection';
+
+const config: SapConfig = {
+  url: 'https://your-sap-server.com',
+  authType: 'basic',
+  username: 'user',
+  password: 'pass',
+  client: '100'
+};
+
+const logger: ILogger = {
+  info: (msg: string) => console.log(msg),
+  error: (msg: string) => console.error(msg),
+  warn: (msg: string) => console.warn(msg),
+  debug: (msg: string) => console.log(msg),
+};
+
+const connection = createAbapConnection(config, logger);
+```
+
+## Troubleshooting
+
+### Module not found
+
+If you get "Cannot find module" error after installation:
+
+```bash
+# Clear cache
+npm cache clean --force
+
+# Reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### TypeScript errors
+
+Ensure TypeScript version compatibility:
+
+```bash
+npm install --save-dev typescript@^5.9.2
+```
+
+### Build errors
+
+If building from source fails:
+
+```bash
+# Check Node version
+node --version  # Should be >= 18.0.0
+
+# Rebuild
+npm run build
+```
+
+### Connection errors
+
+**401 Unauthorized**: Check username/password or JWT token  
+**403 Forbidden**: Check user permissions in SAP  
+**ENOTFOUND**: Check SAP URL is correct and reachable  
+**ETIMEDOUT**: Check network/firewall, try increasing timeout
+
+### SSL/TLS errors
+
+For development with self-signed certificates:
+
+```bash
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+```
+
+**⚠️ Warning**: Never use this in production!
+
+## Version Compatibility
+
+| Package Version | Node.js | TypeScript |
+|----------------|---------|------------|
+| 0.1.10         | >= 18.0 | >= 5.0     |
+| 0.1.9          | >= 18.0 | >= 5.0     |
+| 0.1.8          | >= 18.0 | >= 5.0     |
+| 0.1.0 - 0.1.7  | >= 18.0 | >= 4.5     |
+
+## Next Steps
+
+- 📚 Read [USAGE.md](./USAGE.md) for detailed usage examples
+- 🔄 Token refresh is handled by `@mcp-abap-adt/auth-broker` package
+- 💾 Session state persistence is handled by `@mcp-abap-adt/auth-broker` package
+- 🔑 Use [JWT auth CLI tool](./JWT_AUTH_TOOLS.md)
+- 📖 Review [CHANGELOG.md](../CHANGELOG.md) for version history

package/docs/JWT_AUTH_TOOLS.md

@@ -0,0 +1,142 @@
+# JWT Auth Tools
+
+This package ships with a helper CLI (`sap-abap-auth`) to obtain JWT and refresh tokens for SAP BTP ABAP systems.
+
+
+## Prerequisites
+
+- Node.js >= 18
+- Service key JSON for your SAP BTP ABAP instance (from SAP BTP Cockpit)
+- Browser access (for OAuth flow)
+
+
+## Quick Start
+
+```bash
+npx sap-abap-auth auth -k path/to/service-key.json
+```
+
+This launches the OAuth browser flow and prints a `.env` file containing `SAP_JWT_TOKEN`, `SAP_REFRESH_TOKEN`, `SAP_UAA_URL`, etc.
+
+
+## Installation Options
+
+### Local (Project) Install
+
+If `@mcp-abap-adt/connection` is part of your `dependencies` or `devDependencies`, you already have the CLI available:
+
+```bash
+npm install @mcp-abap-adt/connection --save-dev
+npx sap-abap-auth auth -k service-key.json
+```
+
+Pros:
+- CLI travels with your project.
+- No need for global npm installs.
+
+### Global Install
+
+```bash
+npm install -g @mcp-abap-adt/connection
+sap-abap-auth auth -k service-key.json
+```
+
+Pros:
+- Available system-wide.
+- Useful if you run the tool frequently from the terminal.
+
+### On-Demand (One-off) Usage
+
+```bash
+npx @mcp-abap-adt/connection sap-abap-auth auth -k service-key.json
+```
+
+Pros:
+- No install needed.
+- Perfect for quick usage on CI or temporary machines.
+
+## CLI Usage
+
+```bash
+# Show help
+sap-abap-auth --help
+
+# Authenticate using service key JSON
+sap-abap-auth auth -k service-key.json
+
+# Use specific browser (chrome, firefox, edge, system, none)
+sap-abap-auth auth -k service-key.json --browser chrome
+
+# Output to custom file (default: .env)
+sap-abap-auth auth -k service-key.json --output .env.production
+
+# Print tokens to stdout (no file)
+sap-abap-auth auth -k service-key.json --browser none --output -
+```
+
+### Full Command Reference
+
+| Option                   | Description                                          |
+|-------------------------|------------------------------------------------------|
+| `-k, --key <path>`      | Path to service key JSON (required)                  |
+| `-b, --browser <name>`  | Browser to open (chrome, edge, firefox, system, none)|
+| `-o, --output <path>`   | Output `.env` path (`-` for stdout, defaults to `.env`) |
+| `--config <path>`       | Use config file with saved credentials               |
+| `--no-open`             | Same as `--browser none`                             |
+| `--help`                | Show help                                            |
+
+
+## Using Generated Tokens
+
+After running the CLI, you get `.env` similar to:
+
+```
+# Token Expiry Information (auto-generated)
+# JWT Token expires: Monday, December 25, 2025 at 10:30:45 AM UTC
+# JWT Token expires at: 2025-12-25T10:30:45.000Z
+# Refresh Token expires: Tuesday, January 25, 2026 at 10:30:45 AM UTC
+# Refresh Token expires at: 2026-01-25T10:30:45.000Z
+
+SAP_URL=https://<your-abap-instance>.abap.whatever.sap
+SAP_AUTH_TYPE=jwt
+SAP_JWT_TOKEN=eyJhbGciOi...
+SAP_REFRESH_TOKEN=eyJraWQiOi...
+SAP_UAA_URL=https://<your>-authentication.<region>.hana.ondemand.com/oauth/token
+SAP_UAA_CLIENT_ID=sb-<id>
+SAP_UAA_CLIENT_SECRET=<secret>
+```
+
+**Note:** The token expiry information at the top of the `.env` file is automatically generated by decoding the JWT tokens. This helps you:
+- Know when tokens will expire
+- Plan token refresh in advance
+- Troubleshoot authentication issues related to expired tokens
+
+If a token's expiry cannot be determined (e.g., non-standard JWT format), a comment will indicate this.
+
+Load it in your project:
+
+```bash
+source .env
+
+```
+
+Or configure `SapConfig` directly:
+
+```ts
+import { createAbapConnection } from "@mcp-abap-adt/connection";
+
+const connection = createAbapConnection({
+  url: process.env.SAP_URL!,
+  authType: "jwt",
+  jwtToken: process.env.SAP_JWT_TOKEN!,
+});
+
+// Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
+// The refresh token credentials in .env are used by auth-broker, not connection
+```
+
+
+## Automating in CI
+
+You can run the CLI once locally, store `.env` in secure storage, then load those variables in CI/CD to feed `@mcp-abap-adt/connection`. بهدف 
+

package/docs/MIGRATION-2.0.md

@@ -0,0 +1,114 @@
+# Migrating to the explicit session lifecycle
+
+The connection now owns its session, and says so. If your code never called
+`connect()`, it will fail at startup rather than at the first request — the
+better failure, but a new one.
+
+## What breaks, and what to do
+
+### 1. `connect()` is required
+
+```typescript
+const connection = createAbapConnection(config, logger);
+await connection.connect();          // ← add this
+await connection.makeAdtRequest(...);
+```
+
+Without it every request is refused with `ADT_NOT_CONNECTED` and nothing
+reaches the server.
+
+**Why it changed.** Requests used to establish the session on the fly, which
+meant a caller could never tell whether it had a session, whose it was, or
+whether the one it locked in was still there. That is what let the connector
+replace the session under a caller holding a lock without saying anything.
+
+### 2. `connect()` rejects on failure
+
+It used to log a warning and resolve anyway, deferring the work to the first
+request. Now a resolved promise means a usable session exists.
+
+```typescript
+try {
+  await connection.connect();
+} catch (error) {
+  // Handle it here, at startup, where it is cheap.
+}
+```
+
+If you never checked the result of `connect()`, you were relying on that
+deferral. The failure has not appeared — it has moved to where you can see it.
+
+**Kerberos**: `connect()` now surfaces a limitation that used to be hidden. If
+the server continues the SPNEGO exchange (a 401 carrying a `Negotiate` token),
+this client cannot continue it — the GSS context is not retained — and
+`connect()` fails saying so. Previously the same situation resolved and failed
+later, on the first request, as an unrelated-looking 401.
+
+### 3. Requests are refused after a teardown
+
+`disconnect()` and `reset()` stop the connection from serving requests until the
+next `connect()`. An in-flight request is not cut off and not waited for either:
+it runs to completion, and its result is fenced so it cannot touch a session
+established since.
+
+### 4. If you hold locks, do not let a timeout cut the span
+
+The connection does **not** track your locks. It does not know one exists, what
+object it covers, or what would release it — pairing every LOCK with its UNLOCK
+belongs to `@mcp-abap-adt/adt-clients`, which holds the handles.
+
+What this layer can do is not let a short timeout abort a request mid-span, which
+would leave an operation whose outcome you cannot determine — a `LOCK` that may
+have succeeded server-side, with a handle you never received:
+
+```typescript
+connection.beginCriticalSection();
+try {
+  const handle = await lock(connection, 'ZCL_MY_CLASS');
+  await update(connection, 'ZCL_MY_CLASS', handle);
+  await unlock(connection, 'ZCL_MY_CLASS', handle);
+} finally {
+  connection.endCriticalSection();
+}
+```
+
+This is not new in 2.x — it has been available since 1.9.0 and is unchanged.
+
+### 5. A new error you should handle
+
+`ADT_SESSION_REPLACED` means the SAP session is gone. It is raised whenever the
+session identity changes under us, and whenever the server itself says the session
+no longer exists. **Your lock handle is dead**: unlocking with it will not work, and the
+object may still be locked on the server. The connector does not retry such
+a request — retrying blindly is what produced further orphaned locks in the
+field.
+
+```typescript
+// (connection already established)
+try {
+  await connection.makeAdtRequest(...);
+} catch (error) {
+  if (error.code === 'ADT_SESSION_REPLACED') {
+    // Reconnect, then deal with the lock you can no longer release.
+  }
+}
+```
+
+## What did NOT change
+
+- `makeAdtRequest()` keeps its signature and its behaviour on a healthy session.
+- `IAbapConnection` is unchanged: `connect()` was already on it. The rest of the
+  lifecycle API lives on the HTTP connection classes for now, so code holding
+  the interface type sees no new members and needs no change.
+- Automatic recovery still happens: a CSRF token refresh, a 401 retry, a JWT
+  refresh. What changed is that a recovery which **replaces the session** while
+  you hold a lock now fails loudly instead of continuing on the new one.
+- RFC connections already required an open client, so nothing there changes for
+  callers.
+
+## What to check on your side
+
+- every place a connection is created — does `connect()` follow it?
+- every place `connect()` is called — is its rejection handled?
+- error handling around lock/unlock flows — is `ADT_SESSION_REPLACED` handled,
+  or does it fall into a generic catch that retries?

package/docs/SCOPE.md

@@ -0,0 +1,44 @@
+# Scope and Boundaries
+
+This package is **one component of the `@mcp-abap-adt/*` family**. Each package owns one concern; together they form an SAP ABAP tooling stack. Keeping the boundaries clear is important — several features that look natural to add here actually belong in sibling packages, and some that look missing (like RFC-to-cloud) do not exist anywhere in the ecosystem because the underlying technology does not support them.
+
+## What this package does
+
+- **HTTP transport to SAP ADT** — request dispatch, CSRF token fetch, cookie and session handling, stateful/stateless session control.
+- **The session lifecycle** — establishing a session and refusing to work without one, tearing it down without cutting in-flight requests, tracking which SAP session it is talking to, and telling the caller when that session is lost while a lock is held. See [USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle).
+- **RFC transport to on-premise SAP** — via `@mcp-abap-adt/sap-rfc-lite` + NW RFC SDK, calling `SADT_REST_RFC_ENDPOINT` (the same FM Eclipse ADT uses on on-prem).
+- **Applying credentials** handed to it by the caller (Basic user/password, Bearer JWT, SAML session cookies).
+
+## What this package does NOT do, and where it lives instead
+
+| Concern | Belongs in |
+|---|---|
+| Token acquisition (SAML/OAuth2 flows, browser login, PKCE) | `@mcp-abap-adt/auth-broker` |
+| Token validation, refresh, re-authentication, expiry tracking | consumer via `ITokenProvider` (from `@mcp-abap-adt/interfaces`) |
+| Session state persistence across processes | `@mcp-abap-adt/auth-broker` |
+| Auth-type constants, provider error codes, auth lifecycle contracts | `@mcp-abap-adt/interfaces` |
+
+The rule: **if it is about *acquiring* or *refreshing* credentials, it is not our job.** We receive credentials that are valid at call time and use them. The consumer is responsible for handing us fresh ones — they know their IdP, their refresh cadence, their re-auth UX.
+
+## Why there is no RFC to SAP BTP / cloud
+
+Short answer: because SAP does not support it that way, and Eclipse ADT does not do it that way either.
+
+**1. Eclipse ADT talks to cloud over HTTP, not RFC.**
+The `com.sap.adt.communication.http.*` package is the only transport Eclipse ADT uses for ADT itself. Cloud login in Eclipse goes through `SamlWithReentranceTicketLogonFacade` → `IcfEndpointBasedSystemUrlInfoProvider` → `HttpLowLevelConnection.sendRequest`. This is an HTTP flow via the ABAP ICF (Internet Communication Framework) endpoint, with a browser SAML login minting a short-lived reentrance ticket, which is then exchanged for a `MYSAPSSO2` session cookie over HTTP. There is no RFC anywhere in this path. JCo/RFC calls that appear in Eclipse logs come from unrelated features (GUI integration, JCo destination tests) — not ADT.
+
+**2. NW RFC SDK has no JWT or SAML-2.0-XML logon parameter.**
+Inspection of `sapnwrfc.h` and the SDK's reference `sapnwrfc.ini` confirms the supported client logon parameters are: `USER`/`PASSWD`, `X509CERT`, `MYSAPSSO2` (accepts SSO2 tickets and SAP-internal "assertion tickets", *not* SAML 2.0 XML assertions), plus SNC (`SNC_QOP`, `SNC_MYNAME`, `SNC_PARTNERNAME`, `SNC_LIB`) for Kerberos/x509 over RFC. For WebSocket-RFC: `WSHOST`/`WSPORT`, `ALIAS_USER`, `TLS_CLIENT_PSE`, `TLS_CLIENT_CERTIFICATE_LOGON`. No `JWT`, no `BEARER`, no `SAML_ASSERTION`, no `OAUTH` keys exist in the SDK headers.
+
+**3. `@mcp-abap-adt/sap-rfc-lite` is a pure passthrough.**
+It forwards every `(name, value)` pair from the JS `Client(params)` object to `RFC_CONNECTION_PARAMETER[]` without filtering. So the wrapper is not a constraint — the constraint is the SDK itself.
+
+**4. For BTP on-prem scenarios (Cloud Connector), the JWT→x509/SNC swap happens server-side in the CC.** The client-side RFC call still carries classic credentials (x509 + SNC), not the JWT. Supporting that would be adding SNC-over-RFC for on-prem backends behind a CC tunnel — an on-prem extension, not a "cloud RFC" feature.
+
+**Conclusion:** "RFC to cloud" is not a missing feature that would be useful to add; it is a category error. ADT to cloud = HTTP (already supported here). RFC to on-prem = supported here via `connectionType: 'rfc'`. Anything claiming a third combination does not map to what the SAP stack actually exposes.
+
+## See also
+
+- [`INSTALLATION.md`](./INSTALLATION.md)
+- [`USAGE.md`](./USAGE.md)
+- Sibling packages: `@mcp-abap-adt/interfaces`, `@mcp-abap-adt/sap-rfc-lite`, `@mcp-abap-adt/auth-broker`