@mcp-abap-adt/connection 3.0.0 → 5.0.0

package/dist/session/SessionStrategy.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * How a session is opened on the server, and how the server is told we are
+ * done with it.
+ *
+ * Two systems, two mechanisms, one meaning. On ABAP Cloud a session is a
+ * resource: it is asked for at `/sap/bc/adt/core/http/sessions` and the
+ * response publishes its own address, which is what a `DELETE` is sent to. On
+ * on-prem there is no such resource — the logon call is the establishing
+ * request itself, and the platform's `/sap/public/bc/icf/logoff` is how it is
+ * given back.
+ *
+ * **Both are notifications, not commands.** They say "we have finished with
+ * this session". Whether the system frees it now, later, or keeps it to reuse
+ * is the system's business, and nothing here checks afterwards or depends on
+ * the answer. Measured on a trial: the `DELETE` is answered `200` and the
+ * session is still listed a moment later; the logoff is answered `200` and it
+ * is not. Neither is a failure — they are two systems deciding differently
+ * about a message they both accepted.
+ *
+ * Split by what the server publishes rather than by which system we think we
+ * are talking to: `openSession()` asks, and a system that has no such resource
+ * says so. Guessing the platform would be a guess; asking is not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStrategy = void 0;
+class SessionStrategy {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+}
+exports.SessionStrategy = SessionStrategy;

package/dist/utils/cookies.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Join two `Cookie` header values, later wins on a repeated name.
+ *
+ * Used wherever a request already carries cookies and more are added: a
+ * credential can BE cookies — a SAML session is handed over as `MYSAPSSO2` —
+ * so writing the session jar over the header drops the very thing the request
+ * authenticates with. Both belong on the wire: one says who we are, the other
+ * which session we are in. A name in both is the session's, because that is the
+ * one the server just issued.
+ */
+export declare function mergeCookieHeaders(existing: string | undefined, incoming: string | undefined): string;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/utils/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/utils/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,CASR"}

package/dist/utils/cookies.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeCookieHeaders = mergeCookieHeaders;
+/**
+ * Join two `Cookie` header values, later wins on a repeated name.
+ *
+ * Used wherever a request already carries cookies and more are added: a
+ * credential can BE cookies — a SAML session is handed over as `MYSAPSSO2` —
+ * so writing the session jar over the header drops the very thing the request
+ * authenticates with. Both belong on the wire: one says who we are, the other
+ * which session we are in. A name in both is the session's, because that is the
+ * one the server just issued.
+ */
+function mergeCookieHeaders(existing, incoming) {
+    const parts = [existing, incoming].filter(Boolean).join('; ');
+    const byName = new Map();
+    for (const part of parts.split(';')) {
+        const pair = part.trim();
+        if (!pair)
+            continue;
+        byName.set(pair.slice(0, pair.indexOf('=')), pair);
+    }
+    return [...byName.values()].join('; ');
+}

package/dist/utils/timeouts.d.ts

@@ -12,4 +12,20 @@ export declare function getTimeout(type?: 'default' | 'csrf' | 'long' | number):
  * permanently dead socket hanging forever.
  */
 export declare function getCriticalSectionTimeout(): number;
+/**
+ * How long `disconnect()` may spend telling the server the session is done.
+ *
+ * **Zero by default: after a disconnect nothing waits on the answer.** Waiting
+ * is for steps whose successor depends on the server having caught up — lock,
+ * update, unlock, activate, each needing the one before it to have landed.
+ * A teardown has no successor: the session is marked unneeded, the server
+ * reclaims it whenever it reclaims it, and a caller blocked on that round trip
+ * has bought nothing while holding up the serializing tail, where every later
+ * connect and disconnect queues behind it.
+ *
+ * The knob exists for a caller that wants a bounded wait anyway — a test
+ * asserting the logoff landed, a script that would rather see the failure —
+ * and is theirs to set per call via `ISessionLifecycleAware.disconnect`.
+ */
+export declare function getReleaseDeadline(): number;
 //# sourceMappingURL=timeouts.d.ts.map

package/dist/utils/timeouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/utils/timeouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C,wBAAgB,gBAAgB,IAAI,cAAc,CAajD;AAED,wBAAgB,UAAU,CACxB,IAAI,GAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAkB,GACrD,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD"}
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/utils/timeouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C,wBAAgB,gBAAgB,IAAI,cAAc,CAajD;AAED,wBAAgB,UAAU,CACxB,IAAI,GAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAkB,GACrD,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/utils/timeouts.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getTimeoutConfig = getTimeoutConfig;
 exports.getTimeout = getTimeout;
 exports.getCriticalSectionTimeout = getCriticalSectionTimeout;
+exports.getReleaseDeadline = getReleaseDeadline;
 function getTimeoutConfig() {
     const defaultTimeout = parseInt(process.env.SAP_TIMEOUT_DEFAULT || '45000', 10);
     const csrfTimeout = parseInt(process.env.SAP_TIMEOUT_CSRF || '15000', 10);
@@ -32,3 +33,21 @@ function getTimeout(type = 'default') {
 function getCriticalSectionTimeout() {
     return parseInt(process.env.SAP_TIMEOUT_CRITICAL || '600000', 10);
 }
+/**
+ * How long `disconnect()` may spend telling the server the session is done.
+ *
+ * **Zero by default: after a disconnect nothing waits on the answer.** Waiting
+ * is for steps whose successor depends on the server having caught up — lock,
+ * update, unlock, activate, each needing the one before it to have landed.
+ * A teardown has no successor: the session is marked unneeded, the server
+ * reclaims it whenever it reclaims it, and a caller blocked on that round trip
+ * has bought nothing while holding up the serializing tail, where every later
+ * connect and disconnect queues behind it.
+ *
+ * The knob exists for a caller that wants a bounded wait anyway — a test
+ * asserting the logoff landed, a script that would rather see the failure —
+ * and is theirs to set per call via `ISessionLifecycleAware.disconnect`.
+ */
+function getReleaseDeadline() {
+    return parseInt(process.env.SAP_RELEASE_DEADLINE_MS || '0', 10);
+}

package/docs/INDEX.md

@@ -15,6 +15,7 @@ mcp-abap-connection/
 │   ├── INSTALLATION.md             # Setup and installation guide
 │   ├── USAGE.md                    # API documentation and examples
 │   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── MIGRATION-4.0.md            # JWT error classification: 401 refreshes, 403 propagates
 │   ├── 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
@@ -41,6 +42,10 @@ mcp-abap-connection/
 ### Core Features
 - 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
 
+### Upgrading
+- 🧱 [Migrating to 4.0.0](./MIGRATION-4.0.md) - JWT error classification: a 401 refreshes, a 403 propagates with the server's message
+- 🧱 [Migrating to 2.0.0](./MIGRATION-2.0.md) - The explicit session lifecycle: `connect()` is required
+
 ### Version Information
 - 📋 [CHANGELOG](../CHANGELOG.md) - Complete version history, including what the latest release changed
 

package/docs/INSTALLATION.md

@@ -163,7 +163,9 @@ const logger = {
   debug: (msg) => console.log('[DEBUG]', msg),
 };
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 
 connection.connect()
   .then(() =>
@@ -231,7 +233,9 @@ const logger: ILogger = {
   debug: (msg: string) => console.log(msg),
 };
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 ```
 
 ## Troubleshooting

package/docs/MIGRATION-2.0.md

@@ -46,7 +46,7 @@ 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
+`disconnect()` stops 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.

package/docs/MIGRATION-4.0.md

@@ -0,0 +1,95 @@
+# Migrating to 4.0.0: the server's error reaches you
+
+A JWT connection used to answer some failures with an error of its own making:
+
+```
+Error: JWT token has expired. Please re-authenticate.
+```
+
+It said that for a **401** and for a **403** alike, and it threw the original `AxiosError` away
+along with the status and the body. Now the server's error reaches the caller unchanged, and only
+a 401 is treated as a credential problem.
+
+## What breaks, and what to do
+
+### 1. That message is gone
+
+If anything matches on it, it will stop matching.
+
+```typescript
+// before
+catch (error) {
+  if (error.message.includes('JWT token has expired')) {
+    await reauthenticate();
+  }
+}
+
+// after
+catch (error) {
+  if (error.response?.status === 401) {
+    await reauthenticate();
+  }
+}
+```
+
+`error.response.status` and `error.response.data` are available now — they were not before,
+because the replacement error carried neither.
+
+**Why it changed.** The message was wrong about half the cases it was used for. A 403 is not an
+expired token, and telling a caller to re-authenticate for one sends them to fix the single thing
+that is not broken.
+
+### 2. A 403 no longer triggers a token refresh
+
+It propagates as it arrived. If your code relied on a refresh happening after a 403 — for
+instance to recover from an authorization gap that a *different* principal would not have — that
+no longer happens, and it never worked for the reason you may have assumed: a refreshed token
+belongs to the same caller and cannot change a permissions answer.
+
+What a 403 usually carries is worth reading:
+
+```xml
+<exc:exception>
+  <type id="ExceptionResourceNoAuthorization"/>
+  <message lang="EN">You are not authorized to make changes (authorization object S_DEVELOP)</message>
+</exc:exception>
+```
+
+The authorization object is named. That is actionable; "please re-authenticate" was not.
+
+### 3. A 401 still refreshes, and now says so when it does not help
+
+The happy path is unchanged: a 401 with an injected `ITokenRefresher` fetches a new token,
+re-establishes the session and retries. What changed is the unhappy one — when the retry comes
+back 401 as well, the original error is rethrown and an `ERROR`-level log line explains that the
+credential may genuinely need re-authentication.
+
+## What did not change
+
+- `ITokenRefresher` and how it is injected;
+- that a credential renewal replaces the SAP session — with a lock window open, a request still
+  fails with `ADT_SESSION_REPLACED` rather than continuing on a session your lock is not in (see
+  [STATEFUL_SESSION_GUIDE.md](./STATEFUL_SESSION_GUIDE.md));
+- every other authentication type. `BaseAbapConnection`, `SamlAbapConnection`,
+  `CertificateAbapConnection` and `KerberosAbapConnection` never refreshed tokens and never
+  synthesised an error in place of the server's.
+
+## Under the hood, if you are debugging
+
+Concurrent requests that hit the same expired token now share **one** renewal — one token fetch
+and one session re-establishment between them — rather than each running its own teardown and
+recovery in sequence. If you have log-line counts or timing expectations built around the old
+behaviour, they will change; the observable contract does not.
+
+## Where this came from
+
+Issue [#30](https://github.com/fr0ster/mcp-abap-connection/issues/30), found while probing ATC on
+a cloud trial: creating a classic program was reported as an expired token on three consecutive
+runs, while the same session was answering other requests with 200. It took bypassing the
+connector on the same credential to see the 403 and the `S_DEVELOP` message underneath.
+
+One question is deliberately left open and tracked in
+[#32](https://github.com/fr0ster/mcp-abap-connection/issues/32): whether some BTP setup answers an
+*invalid* token with 403 rather than 401. Nothing captured shows that it does, and preserving the
+original error is what makes the assumption safe to be wrong about — a caller would then see the
+server's own 403 instead of a misleading message.

package/docs/MIGRATION-5.0.md

@@ -0,0 +1,116 @@
+# Migrating to 5.0.0
+
+Two things changed, and the second is why the first was possible.
+
+**A connection now closes what it opened.** `disconnect()` tells the server the
+session is finished instead of only dropping the cookie, and `connect()` fails
+when the server opened no session rather than handing back a connection whose
+first lock would be dead.
+
+**The class you take says which system you are dialling, not which credential
+you hold.** `AdtOnPremConnector` and `AdtCloudConnector` are handed an auth
+provider; the five auth classes still work and are deprecated.
+
+---
+
+## If you use `createAbapConnection()`
+
+It still works, unchanged, and now warns once per call that the connection is
+being chosen from `authType`. Say which system instead:
+
+```ts
+// before
+const conn = createAbapConnection(config, logger, undefined, tokenRefresher);
+
+// after
+const conn = createAbapConnection(config, logger, undefined, tokenRefresher, {
+  system: 'cloud',   // or 'onprem'
+});
+```
+
+Nothing is detected. The two systems do not manage sessions the same way, and
+asking the server which it is does not work: `/sap/bc/adt/core/http/sessions`
+answers on on-prem too, and its `DELETE` there leaves the session open while the
+platform logoff removes it. Only you know where you are pointing.
+
+## If you build a connection class directly
+
+```ts
+// before                                    // after
+new BaseAbapConnection(cfg, log)             new AdtOnPremConnector(cfg, new BasicAuthProvider(user, pass), log)
+new JwtAbapConnection(cfg, log, id, refr)    new AdtCloudConnector(cfg, new TokenAuthProvider(refr), log)
+new SamlAbapConnection(cfg, log)             new AdtOnPremConnector(cfg, new SamlAuthProvider(cookies), log)
+new CertificateAbapConnection(cfg, log)      new AdtOnPremConnector(cfg, new CertificateAuthProvider(loader, cfg), log)
+```
+
+`KerberosAbapConnection` has no provider yet — its SPNEGO exchange *is* the CSRF
+fetch — so keep using the class. See #35.
+
+The old classes are not removed and not scheduled for removal here.
+
+## `reset()` is gone — BREAKING
+
+There is no local-only discard, because there is no local-only session: it lives
+on the server, and dropping the cookie leaves it there.
+
+```ts
+conn.reset();                 // before
+await conn.disconnect();      // after — and connect() again to carry on
+```
+
+A caller that does not want to wait simply does not `await` it, which is what
+`reset()` was mostly used for. `RfcAbapConnection` keeps `close()`.
+
+## `connect()` can now fail where it used to warn — BREAKING
+
+When the server authenticates the request but opens no session, `connect()`
+rejects with `ADT_NOT_CONNECTED` and a message saying what happened, what still
+works, and the usual cause. It used to log a warning and hand the connection
+back — and the failure then surfaced a request later, as `400 Session not found`
+with the object half-edited.
+
+Verified rather than assumed: a connection that received no `SAP_SESSIONID` is
+listed in the server's own session list as **nothing at all**.
+
+Nothing is retried on your behalf. Whether to wait, retry, or release sessions
+the user still holds depends on things only you know.
+
+## `disconnect()` now makes a network call
+
+It tells the server the session is finished. Two consequences:
+
+- **It can wait.** By default it does not: `SAP_RELEASE_DEADLINE_MS` is `0`,
+  because waiting is for steps whose successor needs the server to have caught
+  up, and a teardown has none. Pass `disconnect({ deadlineMs })` if you want a
+  bounded wait — the deadline bounds the **wait**, never the request.
+- **Requests still in flight will start failing.** The session they are running
+  on is the one being released. That is you having asked to disconnect, not a
+  race — finish or abandon your chains first.
+
+It still never throws, including on a nonsense `deadlineMs`: its place is a
+`finally`, where an exception would replace the error that sent you there.
+
+## Token renewal, if you use a provider
+
+Nothing to do, but worth knowing what changed. The connector no longer caches
+the token it was given. It asks the provider per request — cheap, because the
+provider caches — and on a `401` it tells the provider its answer was refused
+(`refreshToken()`, per that contract), asks again, and only if the answer
+changed rebuilds the session and retries once. An unchanged answer means the
+server refused those credentials, and the `401` reaches you.
+
+So a password does the right thing with no configuration, and a bearer token is
+renewed without a class of its own.
+
+## Sessions are a shared, per-user resource
+
+Not an API change, a fact worth having. The limit is per user and the pool is
+shared with everything else logged on as them, a SAP GUI session included. The
+timeout is **idle-based**: a connection that keeps working keeps its session,
+one that goes quiet past the window loses it. There is no keepalive timer here,
+deliberately — how long to hold a session is yours to decide.
+
+And the shape of the problem this release addresses, seen from the other end: a
+process that opens a connection per check and never disconnects filled a
+system's session list at one session every ten seconds. Releasing what you open
+is half of it; opening one connection instead of one per check is the other.

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -29,7 +29,9 @@ The connection layer **does not** decide when to lock/unlock objects—that logi
 ```ts
 import { createAbapConnection } from '@mcp-abap-adt/connection';
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 await connection.connect();   // required before any request
 
 // Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
@@ -47,11 +49,11 @@ connection.setSessionType('stateless');
 ## Knowing Which Session You Are In
 
 ```ts
-import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+import { AdtOnPremConnector, BasicAuthProvider } from '@mcp-abap-adt/connection';
 
 // getSessionIdentity() is on the HTTP connection classes, NOT on the
 // IAbapConnection type that createAbapConnection() returns.
-const connection = new BaseAbapConnection(config, logger);
+const connection = new AdtOnPremConnector(config, new BasicAuthProvider(user, pass), logger);
 await connection.connect();
 
 // Which SAP session this connection is talking to. Changes only when the
@@ -82,6 +84,12 @@ Every ADT request issued through `makeAdtRequest` automatically:
 
 This logic is transparent to callers (Builders, handlers, CLI scripts).
 
+On a JWT connection one case is **not** transparent, and cannot be: a 401 that leads to a token
+refresh also replaces the SAP session, because the renewed credential cannot keep the old one.
+Inside a lock window that surfaces as `ADT_SESSION_REPLACED` rather than a request quietly
+continuing on a session your lock is not in. A 403 never does this — it is an authorization
+answer, not a credential one, and nothing is torn down for it.
+
 ---
 
 ## Interaction With ADT Clients
@@ -96,19 +104,83 @@ This logic is transparent to callers (Builders, handlers, CLI scripts).
 
 ---
 
+## What This Layer Actually Solves
+
+The link to the ABAP session is not guaranteed, and that is the whole problem:
+
+- the ABAP session can be terminated by the system while this client still
+  believes it has one — the next lock-bound request answers
+  `400 "Session not found"`;
+- or it is never created at all, because the system will not open another one
+  for this user right now.
+
+Both are reported, neither is worked around. `connect()` fails with the reason
+when no session was opened; a session lost afterwards surfaces as
+`ADT_SESSION_REPLACED` rather than a request quietly continuing somewhere it
+does not belong. What to do about either — wait, retry, reconnect, release
+sessions the user still holds, carry on read-only — is the caller's decision,
+made with the cookies and the answers in hand.
+
+## A Lock Lives In The ABAP Session
+
+There are two sessions here, and they are not the same thing:
+
+- the **HTTP session** — the conversation this client is having. It exists as
+  long as the cookies do, and nothing about it is in doubt;
+- the **ABAP session** — named by `SAP_SESSIONID_<SID>_<CLIENT>`, and the thing
+  locks are bound to.
+
+The doubt is only ever about the second. It may not have been created, or it may
+have been terminated while this client still holds the cookies and believes it
+has one — and a lock is dead in either case, whether or not the client noticed.
+
+Two ways to lose one, and they are different problems:
+
+- **The server never opened one.** No `SAP_SESSIONID` came back, so there is no
+  ABAP session known to this connection and nothing a lock could be bound to —
+  while the HTTP side is perfectly fine, which is why it does not look like a
+  failure at all. `connect()` refuses rather than handing back a connection
+  whose first lock would be dead on arrival. Sessions are limited per user and shared with every other tool
+  logged on as them, so this says nothing about your code — it says the system
+  would not open another one right now.
+- **It timed out while you were quiet.** The timeout is an idle one, and it is
+  the *silence* that spends it, not the elapsed time. Measured on an on-prem
+  system with a 30-minute window: a small request once a minute kept one session
+  alive for 45 minutes with its identity unchanged, straight past the mark.
+
+So a long chain under a lock is safe while it is doing something, and at risk
+while it waits. **Any request in the session resets the window** — a poll, a
+read, a status check. There is deliberately no keepalive timer in this package:
+holding a session alive means holding a scarce, shared slot, and deciding to do
+that belongs to the caller who knows why the session is worth keeping.
+
+**The cookies are the session.** Nothing else ties a caller to one, so a second
+connection given the same cookie jar works in the same ABAP session and can use
+the locks taken in it — that is what makes handing them over a way to continue
+someone else's work. It cuts both ways: `disconnect()` ends the session for
+everyone holding those cookies, not just for the object it was called on, and no
+connection can see the copies. Deciding who may hold them, and who is allowed to
+close, belongs to whoever passes them around.
+
+The server never tells the client how long it has: the session cookie carries no
+expiry and no response header mentions one. The only honest signals are the ones
+you get by asking — `getSessionIdentity()` for which session you are in, and
+`ADT_SESSION_REPLACED` when the one you were in is gone.
+
 ## Troubleshooting
 
-- **CSRF token errors**: discard the session and establish a new one. `reset()`
-  does that, but it lives on the HTTP connection classes and is **not** on the
-  `IAbapConnection` type `createAbapConnection()` returns — reach it through a
-  concrete type:
+- **CSRF token errors**: discard the session and establish a new one. That is
+  `disconnect()` followed by `connect()` — there is no local-only discard, because
+  dropping the cookie leaves the ABAP session open on the server. Both live on
+  the HTTP connection classes and are **not** on the `IAbapConnection` type
+  `createAbapConnection()` returns — reach them through a concrete type:
 
   ```ts
-  import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+  import { AdtOnPremConnector, BasicAuthProvider } from '@mcp-abap-adt/connection';
 
-  const connection = new BaseAbapConnection(config, logger);
-  connection.reset();          // queues the cleanup; refuses requests meanwhile
-  await connection.connect();  // a new session, explicitly
+  const connection = new AdtOnPremConnector(config, new BasicAuthProvider(user, pass), logger);
+  await connection.disconnect(); // ends the session on the server, then clears
+  await connection.connect(); // a new session, explicitly
   ```
 - **Session expired**: reauthenticate to obtain a new session.
 - **Multiple connections**: each `createAbapConnection` instance maintains its own cookie jar; share the instance if you need continuity.