@mcp-abap-adt/connection 1.10.1 → 2.0.0

package/docs/INDEX.md

@@ -0,0 +1,106 @@
+# Documentation Index
+
+**Package:** `@mcp-abap-adt/connection`  
+**Version:** see [CHANGELOG.md](../CHANGELOG.md) — kept there rather than
+duplicated here, where it went stale by eight minor versions.
+
+## Package Structure
+
+```
+mcp-abap-connection/
+├── README.md                 # Main package documentation
+├── CHANGELOG.md             # Version history and changes
+├── docs/                    # Detailed documentation
+│   ├── INDEX.md                    # This file - documentation overview
+│   ├── INSTALLATION.md             # Setup and installation guide
+│   ├── USAGE.md                    # API documentation and examples
+│   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── SCOPE.md                    # What this package does and does not own
+│   ├── STATEFUL_SESSION_GUIDE.md   # Stateful requests and lock windows
+│   └── JWT_AUTH_TOOLS.md           # CLI tool for authentication
+├── examples/               # Working code examples
+│   ├── README.md          # Examples overview
+│   └── basic-connection.js # Simple connection example
+├── bin/                   # CLI tools
+│   └── sap-abap-auth.js  # JWT authentication CLI
+└── src/                  # Source code
+    ├── connection/       # Connection classes
+    ├── config/          # Configuration utilities
+    ├── utils/           # Helper functions
+    └── __tests__/       # Unit tests
+```
+
+## Quick Links
+
+### Getting Started
+- 📦 [Installation Guide](./INSTALLATION.md) - How to install and set up the package
+- 📚 [Usage Guide](./USAGE.md) - Basic usage and comprehensive API documentation
+- 📖 [Main README](../README.md) - Package overview and quick start
+- 🧭 [Scope and Boundaries](./SCOPE.md) - What this package does (and does not), sibling packages, and why there is no RFC to cloud
+
+### Core Features
+- 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
+
+### Version Information
+- 📋 [CHANGELOG](../CHANGELOG.md) - Complete version history, including what the latest release changed
+
+### Examples
+- 📁 [Examples Overview](../examples/README.md) - All available examples
+- 🔌 [Basic Connection](../examples/basic-connection.js) - Simple connection setup
+
+## Documentation by Topic
+
+### Authentication
+- **Basic Auth**: [USAGE.md - Basic Authentication](./USAGE.md#basic-authentication-on-premise)
+- **JWT/OAuth2**: [USAGE.md - JWT Authentication](./USAGE.md#jwt-authentication-cloudbtp)
+- **Token Refresh**: Handled by `@mcp-abap-adt/auth-broker` package (removed in 0.2.0)
+- **CLI Tool**: [JWT_AUTH_TOOLS.md](./JWT_AUTH_TOOLS.md)
+
+### Session Management
+- **Overview**: [USAGE.md - Session Management](./USAGE.md#session-management)
+- **Stateful Mode**: Use `setSessionType('stateful')` for session headers
+- **Session State Persistence**: Handled by `@mcp-abap-adt/auth-broker` package
+- **API Methods**:
+  - `getSessionId()` - Get current session ID (auto-generated UUID)
+  - `setSessionType()` - Switch between stateful/stateless modes
+
+### API Reference
+- **Connection Interface**: [USAGE.md - API Reference](./USAGE.md#api-reference)
+- **Configuration Types**: [USAGE.md - Configuration Types](./USAGE.md#configuration-types)
+- **Factory Function**: `createAbapConnection()`
+- **Connection Classes**: `BaseAbapConnection`, `JwtAbapConnection`
+
+## Version Highlights
+
+See [CHANGELOG.md](../CHANGELOG.md). This section used to restate it and drifted
+eight minor versions behind — a second copy of a changelog is a changelog that
+is wrong.
+
+## Documentation Standards
+
+### File Organization
+- **README.md** - Package overview, quick start, basic API
+- **CHANGELOG.md** - All changes, following [Keep a Changelog](https://keepachangelog.com/)
+- **docs/** - Detailed documentation, tutorials, guides
+- **examples/** - Working code examples with README
+
+### Naming Conventions
+- `UPPERCASE.md` - Main documentation files (README, CHANGELOG)
+- `PascalCase.md` - Detailed guides in docs/ folder
+- `kebab-case.js` - Example files
+
+### Content Guidelines
+- Keep README concise, link to detailed docs
+- Include working code examples
+- Document environment variables and configuration
+- Provide troubleshooting sections
+- Show both success and error handling
+
+## Contributing Documentation
+
+When adding new features:
+1. Update CHANGELOG.md with changes
+2. Add usage examples to USAGE.md
+3. Create working examples in examples/
+4. Update README.md if API changes
+5. Add troubleshooting to relevant guide

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,125 @@
+# 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: a teardown drains
+before it clears anything.
+
+### 4. If you hold locks, tell the connection
+
+Available on the HTTP connection classes; see the availability note in
+[USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle).
+
+```typescript
+const token = connection.beginWindow('Class/ZCL_MY_CLASS');
+
+let lockHandle: string | undefined;
+try {
+  lockHandle = await lock(connection, 'ZCL_MY_CLASS');
+} catch (error) {
+  connection.endWindow(token);   // confirmed NOT locked: nothing is held
+  throw error;
+}
+
+try {
+  await update(connection, 'ZCL_MY_CLASS', lockHandle);
+  await unlock(connection, 'ZCL_MY_CLASS', lockHandle);
+  connection.endWindow(token);   // confirmed unlocked: the lock is released
+} catch (error) {
+  // Left open on purpose: the unlock may have failed, never gone out, or come
+  // back with an unknown outcome. Do NOT use a finally here.
+  throw error;
+}
+```
+
+You are not required to use windows at all. Without them a teardown cannot know
+a lock is open, so it will not wait for your unlock and will not report the lock
+if it gives up — it simply tears down, and the object stays locked on the server.
+
+But do not open a window and forget to close it on success: every later teardown
+then waits out `SAP_TIMEOUT_CRITICAL` before reporting it as abandoned.
+
+### 5. A new error you should handle
+
+`ADT_SESSION_REPLACED` means the SAP session is gone. It is raised when a
+replacement happens **while you hold a lock window**, and whenever the server
+itself says the session no longer exists — that second case regardless of any
+window. **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?