@mcp-abap-adt/connection 5.0.0 → 6.0.1

package/CHANGELOG.md

@@ -7,6 +7,246 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.1] - 2026-08-25
+
+### Removed
+
+- **`express` is no longer a dependency.** It was a runtime dependency for one
+  thing: the localhost server in `bin/sap-abap-auth.js` that catches the OAuth2
+  redirect. The library never touched it, and that file already imported
+  `node:http`. Rewritten on `node:http`, which sheds 5.6MB of `node_modules` and
+  the transitive tree the Dependabot bumps kept arriving for — `qs`,
+  `body-parser` and `follow-redirects` were all express's.
+
+  Two things express was doing implicitly are now stated: a request is the
+  redirect only when it is a `GET` for `/callback`, so a browser fetching
+  `/favicon.ico` no longer reaches the handler waiting for an authorization
+  code; and the success page declares `text/html`, which `res.send()` used to
+  infer. Exercised as a server: `200` with the page, `400` without a code, `404`
+  for anything else including a `POST`.
+
+  Runtime dependencies are now `@mcp-abap-adt/interfaces`, `axios`, `commander`
+  and `open`. The end-to-end flow was measured against the BTP trial — see
+  *Verified* below.
+
+### Changed
+
+- **The browser wait is the caller's to set.** `bin/sap-abap-auth.js` waited a
+  fixed five minutes for the redirect, and a real BTP login does not fit in it —
+  the identity provider, a password manager and whatever second factor the
+  tenant asks for all happen before the redirect is issued. Measured twice, and
+  both times the window closed first; the browser then had nowhere to redirect
+  to, which reads as the authentication having failed rather than as a timeout.
+
+  `--timeout <minutes>`, or `SAP_AUTH_TIMEOUT_MS` for a script that would rather
+  not pass an argument, with the flag winning when both are given. Anything that
+  is not a positive number is refused by name rather than silently becoming a
+  default. **The default is now fifteen minutes**, which covered the login this
+  was measured against with room to spare and still bounds an abandoned run.
+
+### Verified
+
+- **The whole chain, end to end**: `bin/sap-abap-auth.js auth` → browser
+  authorization against the tenant's UAA → redirect to `localhost:3001/callback`
+  → code exchanged for a token → `.env` written with `SAP_JWT_TOKEN`,
+  `SAP_REFRESH_TOKEN` and the UAA fields.
+
+- Each seam the express removal touched, measured on the real handler rather
+  than a stand-in: `GET /favicon.ico` answers `404` and does not reach the
+  handler waiting for a code — routing express used to do; `GET /callback` with
+  no code answers `400`; the success page comes back
+  `200 text/html; charset=utf-8`, the Content-Type `res.send()` used to infer
+  and `node:http` will not.
+
+- **The issued token then drove this library** against the trial:
+  `AdtCloudConnector` with `CloudHttpTransport` connected, took a session
+  (`SAP_SESSIONID_TRL_100`), answered a `GET /sap/bc/adt/discovery` with `200`
+  and 444826 bytes of XML, and `disconnect()` left `isConnected()` false.
+
+### Fixed
+
+- **The live RFC suite skips a wire the machine did not install.** It asked for
+  four environment variables and nothing else, so a checkout with an env file
+  and no SAP NW RFC SDK ran the suite anyway and went eleven tests red, all on
+  `@mcp-abap-adt/sap-rfc-lite is not available`. The dependency is `optional` —
+  `npm ci` leaves it out WITHOUT failing, which is what optional means — so
+  nothing warns and the next run is red for a reason unrelated to the change
+  under test.
+
+  Nothing here is configured at build time the way a C package is: the installed
+  optional dependency IS the choice of wire, made at install and readable only
+  at runtime. `canRun()` now reads it with `require.resolve`, asking whether the
+  wire could be taken rather than loading a native addon to find out. Measured
+  in both states: SDK hidden — 11 skipped, 2 passed, green; SDK present — 13
+  passed.
+
+- `RfcTransport` says why it ignores `request.timeout`. No behaviour change: the
+  file contained no occurrence of the word, and that silence read as an
+  oversight. It is deliberate — the SDK exposes no cancel, its per-call
+  `timeout` is parsed into a commented-out branch, and an abandoned call still
+  holds the conversation, so the next one would queue behind a call nobody is
+  waiting for. A deadline that reports failure while the wire stays busy is
+  worse than none, because the error reads as "safe to retry" when it is not.
+  The server bounds the call at `rdisp/max_wprun_time`.
+
+## [6.0.0] - 2026-08-24
+
+The wire owns what is the wire's, and the factory and per-credential classes are
+gone. See [Migration to 6.0](./docs/MIGRATION-6.0.md).
+
+### Added — tooling
+
+- **CI.** Until this release the only workflow ran on a tag, and `Release` went
+  from build straight to `npm pack` — so nothing ran the gate before a merge,
+  and the artifact a tag published had been tested nowhere but on a laptop.
+  `ci.yml` runs `lint:check`, `build`, `jest --no-cache`, `check:docs` and
+  `check:pack` on push and pull request, across ubuntu and windows on Node 18
+  and 20. Windows is in the matrix because npm is `npm.cmd` there and Node will
+  not execute a `.cmd` without a shell. `release.yml` runs the same three checks
+  between build and pack, so a tag is not a route around them.
+
+- **`check:pack`** — inspects `npm pack --dry-run --json` and refuses a tarball
+  carrying a test file, a `.tsbuildinfo`, a `.ts` source, an env file or an
+  npmrc. Both defects it was written for had already shipped once:
+  `dist/__tests__/` and 120KB of compiler bookkeeping, neither visible from
+  `files`, because it is the compiler that decides what `dist` holds.
+
+- **`typecheck:scripts`** — `scripts/*.ts` were checked by nothing, which is how
+  three live verification scripts came to sit on a constructor signature two
+  releases old.
+
+### Changed — packaging
+
+- 111 files / 182KB → 95 / 147KB. Test helpers and the compiler's incremental
+  state no longer ship.
+
+### Added
+
+- **The transport axis is complete and public.** `IAdtTransport` now covers
+  everything true of a wire — carrying a request, addressing it, establishing
+  itself, and whatever session state it keeps — and both ends are objects:
+  `HttpTransport` and `RfcTransport`. `IAdtEstablishContext`, `IRfcConversation`
+  and `RfcConnectionParams` are exported, so a caller handed a seam can name it.
+
+- **`rfcConversationFrom(config)`** — the front door to the RFC wire. Derives
+  `ashost` from the url and `sysnr` from the HTTP port (`80XX` → `XX`, with
+  `SAP_SYSNR` overriding), and loads the SAP NW RFC SDK only when a conversation
+  opens, so a machine without it fails at `connect()` rather than at
+  construction.
+
+- **`RfcTransport` supplies a default `Accept`.** axios adds one over HTTP and
+  nobody had noticed; ADT refuses a request without it with
+  `400 ExceptionResourceBadRequest: Accept header missing`.
+
+### Changed
+
+- **The on-prem connector works over RFC.** It did not, at all. Measured against
+  a real system, three blockers stood one behind the other, all of them HTTP
+  assumptions in the class every connector shares: the CSRF fetch handed
+  `SADT_REST_RFC_ENDPOINT` an absolute URL and dumped it with
+  `STRING_OFFSET_TOO_LARGE`; that endpoint returns no `x-csrf-token` however it
+  is asked, so the exchange could not succeed; and the session fingerprint was a
+  scan for a `SAP_SESSIONID` cookie, so a wire that issues none read as a
+  connection the server had opened no session for.
+
+  The base class did not merely check for cookies — it DEFINED a session as one.
+
+- **`AbstractAbapConnection` keeps the lifecycle and nothing else** (1989 → ~1620
+  lines): the transition queue, teardown epochs, session generations, critical
+  sections, stale-request fencing, 401 classification, the identity policy, and
+  the promise that `disconnect()` settles. Cookies, the cookie jar, the CSRF
+  exchange, affinity headers, axios and addressing all moved to the wire that
+  has them. There is no `if (transport is rfc)` anywhere.
+
+- **A credential refused surfaces** rather than being renewed behind the caller —
+  on `connect()` and on the request path alike. Renewal is the provider's, and it
+  happens on an expiry the provider can see, on every call that asks for a header.
+  See *Removed*, below: nothing here answers a 401 any more.
+
+### Changed — BREAKING
+
+- **The base classes ask nothing.** `AbstractAbapConnection` and
+  `CredentialAbapConnection` contain no config-driven conditional, no optional-member
+  call, and no dispatch on a type or a shape. What a collaborator can do is stated by
+  its type, not discovered at runtime:
+
+  - `IAdtTransport.open()` / `close()` are required — a wire with nothing to open
+    writes an empty method, which is true of it;
+  - `IAuthProvider.prepare()`, `cookies()` and `transportMaterial()` are required for
+    the same reason (needs `@mcp-abap-adt/interfaces` 20.0.0);
+  - `establish()` is the transport's, and the connection delegates to it without
+    asking anything first. The credential contributes a header, cookies and TLS
+    material; earning a CSRF token is the wire's work, because the wire is what
+    holds the session the token is bound to (needs `@mcp-abap-adt/interfaces`
+    21.0.0, where the two credential atoms leave the contract — nothing
+    implemented them);
+  - `skipSessionType` is gone: it described BASIS 7.40, and a deployment is a wire, so
+    it is `LegacyOnPremHttpTransport`;
+  - whether a session exists is `IAdtTransport.sessionEstablished()` — a verdict each
+    wire gives about itself, instead of the connection reading a fingerprint and a flag
+    and deciding for all of them at once.
+
+  A credential you wrote gains three usually-empty members; see
+  [the migration guide](./docs/MIGRATION-6.0.md#writing-your-own-credential).
+
+### Removed
+
+- **The connection no longer answers a `401` for you.** It called `renew()` on the
+  credential, compared the header against the previous one, and rebuilt the session
+  if it had changed — a credential lifetime managed from inside the connection.
+  Renewal on an expiry the provider can SEE still happens, inside
+  `authorizationHeader()`, which is asked per request; the other case — a token the
+  provider still believes in and the server refuses — is a judgement made with what
+  the caller knows, so the refusal surfaces. A refused credential is not a lost
+  session, so the connection stays usable. `TokenAuthProvider` declares
+  `IRenewableCredential` (interfaces 19.0.0), which is what a consumer narrows to
+  before calling `renew()` itself.
+
+- **`disconnect({ deadlineMs })`** takes no arguments, and `SAP_RELEASE_DEADLINE_MS`
+  is gone with it. The parameter bounded a wait for the goodbye to be *answered*,
+  and the method does not act on that answer: it tells the server the session is
+  finished, and whether and when the session is freed is the server's affair. The
+  default was already `0`. Waiting bought a caller nothing while being the one
+  thing that could make a teardown unbounded — the goodbye carries no request
+  timeout by design, so a server that never answered would have held the teardown
+  for the whole deadline. Needs `@mcp-abap-adt/interfaces` 18.0.0, where the
+  parameter leaves the contract. Verified against a live BTP trial before the
+  contract moved: `disconnect()` returned in 1 ms and the goodbye still went out.
+
+- **`SessionStrategy`** and its two implementations. A session mechanism only some
+  wires have, described from inside the class every wire shares and driven by the
+  connection — a second wire abstraction beside `IAdtTransport`. It is the
+  transport's `open()`/`close()` now, which is also what made `connect()` possible
+  over RFC at all.
+
+- **`createAbapConnection()`** and the connection classes it built:
+  `BaseAbapConnection` (`OnPremAbapConnection`), `JwtAbapConnection`
+  (`CloudAbapConnection`), `SamlAbapConnection`, `CertificateAbapConnection`,
+  `KerberosAbapConnection`, `RfcAbapConnection` — 1597 lines. Take a connector,
+  hand it a credential, and hand it a transport — which has no default, because
+  which wire you are on is not something to guess.
+
+- `adaptTransport()`, which dressed a transport in an axios shape so six call
+  sites did not have to be rewritten. They were rewritten.
+
+- `connectionType: 'rfc'` as a way to reach the RFC wire. The wire is an
+  argument now.
+
+  **Kerberos has no direct replacement.** It was single-leg only and untested
+  against a live KDC (#35); a `KerberosAuthProvider` belongs on the credential
+  axis and should be added with a system to test it against.
+
+### Fixed
+
+- Credential cookies are merged into the establishing request rather than
+  overwritten by the wire's own — a SAML session IS that cookie, and replacing
+  it sent the exchange out unauthenticated.
+- The CSRF fallback endpoint is tried only when the primary answers 404. A host
+  that is not answering will not answer a different path, and asking doubled the
+  wait before the real error surfaced.
+- A CSRF token arriving on a refused response (405, or any refusal carrying the
+  header) is kept instead of thrown away by the retry.
+
 ## [5.0.0] - 2026-08-21
 
 A connection now says which system it is, closes what it opens, and is handed its
@@ -1120,7 +1360,9 @@ const connection = createAbapConnection(config, logger);
 - JWT token refresh now properly handles connection errors (401/403 during initial connect)
 - Permission errors (403 with "ExceptionResourceNoAccess") no longer trigger JWT refresh loops
 - Proper separation: base class handles HTTP/session, concrete classes handle auth-specific errors
-[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v5.0.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v6.0.1...HEAD
+[6.0.1]: https://github.com/fr0ster/mcp-abap-connection/compare/v6.0.0...v6.0.1
+[6.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v5.0.0...v6.0.0
 [5.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v4.0.0...v5.0.0
 [4.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v3.0.0...v4.0.0
 [3.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v2.0.0...v3.0.0

package/README.md

@@ -57,13 +57,23 @@ The package uses a clean separation of concerns:
 - **Auth providers** (`BasicAuthProvider`, `TokenAuthProvider`, `SamlAuthProvider`,
   `CertificateAuthProvider`):
   - What a connection authenticates with, passed in
-  - A token provider renews on its own; the connector asks it per request and, on a
-    `401`, tells it the answer was refused before asking again
-
-- **`BaseAbapConnection`, `JwtAbapConnection`, `SamlAbapConnection`,
-  `CertificateAbapConnection`, `KerberosAbapConnection`** (deprecated, still exported):
-  - The previous shape, where the class stated your credential and the session
-    mechanism came with it. See [Migration to 5.0](./docs/MIGRATION-5.0.md)
+  - A token provider renews on its own, and the connector asks it per request — which
+    is how a token that expired between two requests is replaced with nobody
+    deciding to replace it
+  - A `401` **surfaces**. Whether a refusal meant "the token is stale" or "these
+    credentials are refused" is a judgement made with what you know, so the
+    connector does not answer it for you. A credential that can be told to get a
+    new one says so through `IRenewableCredential`, which you narrow to
+
+- **Transports** (`OnPremHttpTransport`, `CloudHttpTransport`, `RfcTransport`):
+  - What a request travels over, and everything that is true of that wire.
+    `HttpTransport` keeps the cookie jar, the CSRF token and the affinity
+    headers; `RfcTransport` translates into `SADT_REST_RFC_ENDPOINT` and keeps a
+    conversation that IS the session
+  - On-prem is where this is a real choice; ABAP Cloud has one wire and its
+    connector takes no such parameter
+  - `rfcConversationFrom(config)` builds what `RfcTransport` needs, deriving
+    `ashost` and `sysnr` and loading the SDK only when a conversation opens
 
 - **`GenericWebSocketTransport`** (concrete, exported):
   - Transport abstraction for realtime WS message flows
@@ -123,6 +133,7 @@ This package interacts with external packages **ONLY through interfaces**:
 
 - 📦 **[Installation Guide](./docs/INSTALLATION.md)** - Setup and installation instructions
 - 📚 **[Usage Guide](./docs/USAGE.md)** - Detailed usage examples and API documentation
+- 🚚 **[Migration to 6.0.0](./docs/MIGRATION-6.0.md)** - the factory and the per-credential classes are removed; RFC is a transport, not a class
 - 🚚 **[Migration to 4.0.0](./docs/MIGRATION-4.0.md)** - a 401 refreshes the token, a 403 reaches you with the server's message; the synthesised "JWT token has expired" is gone
 - 🚚 **[Migration: the explicit session lifecycle](./docs/MIGRATION-2.0.md)** - `connect()` is now required; start here if you are coming from 1.x
 - 💡 **[Examples](./examples/)** - Working code examples
@@ -149,7 +160,13 @@ For detailed installation instructions, see [Installation Guide](./docs/INSTALLA
 ### Basic Usage (On-Premise)
 
 ```typescript
-import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  OnPremHttpTransport,
+  SapConfig,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
 const config: SapConfig = {
   url: "https://your-sap-system.com",
@@ -167,23 +184,37 @@ const logger = {
   debug: (msg: string, meta?: any) => console.debug(msg, meta),
 };
 
-// Create connection
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+// Which system you are dialling is the class you take; which credential it
+// authenticates with is the object you hand it. Neither is detected.
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();   // required before any request
 
 // Make ADT request
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
 ### Cloud Usage (JWT/OAuth2)
 
 ```typescript
-import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtCloudConnector,
+  CloudHttpTransport,
+  SapConfig,
+  TokenAuthProvider,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
 // JWT configuration
 const config: SapConfig = {
@@ -200,23 +231,77 @@ const logger = {
   debug: (msg: string, meta?: any) => console.debug(msg, meta),
 };
 
-// Logger is optional - if not provided, no logging output
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "cloud", // which SYSTEM this is — said, never detected
-});
+// Logger is optional - if not provided, no logging output.
+// A bare string is a token with nothing behind it. Hand `TokenAuthProvider` an
+// `ITokenRefresher` instead and it checks expiry and renews on its own, which
+// is what you want in anything long-lived.
+const connection = new AdtCloudConnector(
+  config,
+  new TokenAuthProvider(config.jwtToken!),
+  new CloudHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();
 
-// Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
+// Note: obtaining and refreshing tokens is @mcp-abap-adt/auth-broker's job
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
+### On-Premise over RFC
+
+The same ADT calls, over `SADT_REST_RFC_ENDPOINT` — the function module Eclipse
+ADT itself uses through JCo — instead of over HTTP. Worth taking on a system
+where stateful HTTP sessions are not usable: an RFC conversation is one ABAP
+session for its whole lifetime, which is the way past `423 invalid lock handle`
+on BASIS < 7.50.
+
+Needs the SAP NW RFC SDK on the machine and `npm install @mcp-abap-adt/sap-rfc-lite`.
+
+```typescript
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  RfcTransport,
+  rfcConversationFrom,
+} from "@mcp-abap-adt/connection";
+
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new RfcTransport(rfcConversationFrom(config), logger),
+  logger,
+);
+
+await connection.connect();
+// Everything above the wire is the same: makeAdtRequest, setSessionType,
+// disconnect. What differs is where the session lives — see below.
+```
+
+**Where to look for it.** An HTTP session is an ICF session and appears in
+**SM05**. An RFC conversation is a gateway client: it appears in **SMGW → Logged
+on Clients** as `NWRFC`, and never in SM05, because there is no ICM in that
+path. Looking for one in the other monitor and finding nothing is not a fault.
+
+There is no cloud equivalent: ABAP Cloud has one wire, and `AdtCloudConnector`
+takes no transport parameter at all.
+
 ### SSO Usage (SAML Session Cookies)
 
 ```typescript
-import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
+import {
+  AdtOnPremConnector,
+  OnPremHttpTransport,
+  SamlAuthProvider,
+  SapConfig,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
 const config: SapConfig = {
   url: "https://your-sap-system.com",
@@ -224,34 +309,49 @@ const config: SapConfig = {
   sessionCookies: "MYSAPSSO2=...; SAP_SESSIONID=...",
 };
 
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+// The cookies ARE the credential here — there is no Authorization header at all.
+const connection = new AdtOnPremConnector(
+  config,
+  new SamlAuthProvider(config.sessionCookies!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();
 
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
 ### Cloud Usage with Automatic Token Refresh
 
-For automatic token refresh on **401** errors, inject `ITokenRefresher`:
+Give `TokenAuthProvider` an `ITokenRefresher` and the provider replaces an
+**expired** token on its own — it is asked per request and checks expiry before
+answering, so nobody decides to renew. A token the source still believes in and
+the server refuses is the other half, and that one **surfaces**:
 
 ```typescript
 import {
   AdtCloudConnector,
-  TokenAuthProvider,
+  CloudHttpTransport,
   SapConfig,
+  TokenAuthProvider,
+  getTimeout,
 } from "@mcp-abap-adt/connection";
 import type { ITokenRefresher } from "@mcp-abap-adt/interfaces";
 
 // Token refresher provides token acquisition and refresh
 // (created by @mcp-abap-adt/auth-broker or custom implementation)
+const currentAccessToken = 'the access token you already hold';
+const exchangeRefreshToken = async () => 'a freshly exchanged access token';
 const tokenRefresher: ITokenRefresher = {
-  getToken: async () => { /* return current token */ },
-  refreshToken: async () => { /* refresh and return new token */ },
+  getToken: async () => currentAccessToken,      // the one you hold
+  refreshToken: async () => exchangeRefreshToken(), // a new one, and cache it
 };
 
 const config: SapConfig = {
@@ -264,19 +364,24 @@ const config: SapConfig = {
 const connection = new AdtCloudConnector(
   config,
   new TokenAuthProvider(tokenRefresher),
+  new CloudHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
   logger,
 );
 await connection.connect();
 
-// On a 401 the connector tells the provider its token was refused, asks again,
-// and only if the answer changed rebuilds the session and retries once. An
-// unchanged answer means the server refused these credentials, and the 401
+// On a 401 nothing here decides to get a new credential: the refusal reaches
+// you. Whether it meant "stale" is a judgement made with what you know, and
+// `renew()` is the seam you make it with. The session is untouched — a refused
 // reaches you. A refresh replaces the SAP session, so if a lock window is open
 // the request fails with ADT_SESSION_REPLACED rather than continuing on a
 // session your lock is not in.
 const response = await connection.makeAdtRequest({
   method: "GET",
   url: "/sap/bc/adt/programs/programs/your-program",
+  timeout: getTimeout("default"),
 });
 ```
 
@@ -297,11 +402,22 @@ See [MIGRATION-4.0.md](./docs/MIGRATION-4.0.md).
 For operations that require session state (e.g., object modifications), you can enable stateful sessions:
 
 ```typescript
-import { createAbapConnection } from "@mcp-abap-adt/connection";
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  OnPremHttpTransport,
+  getTimeout,
+} from "@mcp-abap-adt/connection";
 
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 await connection.connect();
 
 // Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
@@ -312,6 +428,7 @@ await connection.makeAdtRequest({
   method: "POST",
   url: "/sap/bc/adt/objects/domains",
   data: { /* domain data */ },
+  timeout: getTimeout("default"),
 });
 
 // Note: Session state persistence is handled by @mcp-abap-adt/auth-broker package
@@ -320,7 +437,7 @@ await connection.makeAdtRequest({
 ### Custom Logger
 
 ```typescript
-import { ILogger } from "@mcp-abap-adt/connection";
+import { AdtOnPremConnector, BasicAuthProvider, ILogger, OnPremHttpTransport } from "@mcp-abap-adt/connection";
 
 class MyLogger implements ILogger {
   info(message: string, meta?: any): void {
@@ -349,9 +466,15 @@ class MyLogger implements ILogger {
 }
 
 const logger = new MyLogger();
-const connection = createAbapConnection(config, logger, undefined, undefined, {
-  system: "onprem", // which SYSTEM this is — said, never detected
-});
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new OnPremHttpTransport(() => ({}), logger, {
+    client: config.client,
+    baseUrl: config.url,
+  }),
+  logger,
+);
 ```
 
 ## CLI Tool
@@ -441,6 +564,8 @@ type SapConfig = {
 Main interface for ABAP connections.
 
 ```typescript
+import { AbapRequestOptions } from '@mcp-abap-adt/connection';
+import type { AxiosResponse } from 'axios';
 // The shared contract (IAbapConnection), what every connection provides:
 interface AbapConnection {
   connect(): Promise<void>; // REQUIRED before any request; rejects on failure
@@ -451,10 +576,12 @@ interface AbapConnection {
 }
 ```
 
-The HTTP connection classes carry the rest of the session lifecycle. It is on the
-shared contract as a **capability atom** in `@mcp-abap-adt/interfaces` rather than
-as methods on `IAbapConnection`, which is why `RfcAbapConnection` — a transport
-that owns no HTTP session — is unaffected by its existence:
+The connectors carry the rest of the session lifecycle. It is on the shared
+contract as a **capability atom** in `@mcp-abap-adt/interfaces` rather than as
+methods on `IAbapConnection`, so a consumer that only carries requests is
+unaffected by its existence. Note that a connection over RFC has the whole of it
+— what an RFC conversation has none of is a session RESOURCE to open and close
+by address, which is an empty mechanism, not an absent lifecycle:
 
 ```typescript
 // ISessionLifecycleAware
@@ -496,16 +623,35 @@ interface ILogger {
 
 ### Functions
 
-#### `createAbapConnection(config, logger?, sessionId?)`
+#### `rfcConversationFrom(config)`
 
-Factory function to create an ABAP connection instance.
+What `RfcTransport` is constructed with. Derives `ashost` from the url and
+`sysnr` from the HTTP port by the SAP convention that `80XX` is the ICM port for
+system `XX`, which `SAP_SYSNR` overrides for a port that follows no convention.
+
+The SAP NW RFC SDK is loaded when a conversation opens, not when this is called,
+so a machine without it fails at `connect()` with a message saying what to
+install rather than at construction.
+
+```text
+function rfcConversationFrom(config: SapConfig): () => IRfcConversation;
+function rfcParamsFrom(config: SapConfig): RfcConnectionParams;
+```
 
 ```typescript
-function createAbapConnection(
-  config: SapConfig,
-  logger?: ILogger | null,
-  sessionId?: string
-): AbapConnection;
+import {
+  AdtOnPremConnector,
+  BasicAuthProvider,
+  RfcTransport,
+  rfcConversationFrom,
+} from "@mcp-abap-adt/connection";
+
+const connection = new AdtOnPremConnector(
+  config,
+  new BasicAuthProvider(config.username!, config.password!),
+  new RfcTransport(rfcConversationFrom(config), logger),
+  logger,
+);
 ```
 
 #### `CSRF_CONFIG` and `CSRF_ERROR_MESSAGES`
@@ -532,6 +678,12 @@ import { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from '@mcp-abap-adt/connection';
 ```typescript
 import { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from '@mcp-abap-adt/connection';
 
+// Whatever HTTP client your own connection class is built on.
+const yourHttpClient = {
+  get: async (url: string, config: { headers: Record<string, string> }) =>
+    ({ headers: {} as Record<string, string> }),
+};
+
 async function fetchCsrfToken(baseUrl: string): Promise<string> {
   const csrfUrl = `${baseUrl}${CSRF_CONFIG.ENDPOINT}`;
   
@@ -563,6 +715,10 @@ async function fetchCsrfToken(baseUrl: string): Promise<string> {
       await new Promise(resolve => setTimeout(resolve, CSRF_CONFIG.RETRY_DELAY));
     }
   }
+
+  // Unreachable: the last attempt either returns or throws above. Stated so the
+  // function has a return type the compiler can agree with.
+  throw new Error(CSRF_ERROR_MESSAGES.NOT_IN_HEADERS);
 }
 ```