@mcp-abap-adt/interfaces 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.5] - 2025-12-21
+
+### Added
+- **ITokenRefresher Interface**: New interface for dependency injection of token refresh logic into connections
+  - `getToken(): Promise<string>` - Get current valid token (cached or refreshed)
+  - `refreshToken(): Promise<string>` - Force refresh token and save to session store
+  - Created by `AuthBroker.createTokenRefresher(destination)` and injected into `JwtAbapConnection`
+  - Enables connections to handle 401/403 errors transparently without knowing about auth internals
+  - Exported from `@mcp-abap-adt/interfaces` in token domain
+
+### Changed
+- **IAbapConnection Simplified**: Removed implementation details from interface, keeping only consumer-facing methods
+  - Removed `getConfig()` - internal implementation detail
+  - Removed `getAuthHeaders()` - handled internally by `makeAdtRequest()`
+  - Removed `connect()` - handled internally, connection established on first request
+  - Removed `reset()` - internal method for token refresh logic
+  - Kept: `getBaseUrl()`, `getSessionId()`, `setSessionType()`, `makeAdtRequest()`
+  - This change simplifies the interface for consumers who only need to make requests
+
+### Deprecated
+- **IAbapConnectionExtended**: Added for backward compatibility, extends `IAbapConnection` with removed methods
+  - `getConfig()`, `getAuthHeaders()`, `connect()`, `reset()`
+  - Will be removed in next major version
+  - Use `IAbapConnection` for new code
+
+## [0.2.4] - 2025-12-21
+
+### Added
+- **Headless Browser Mode**: Added `"headless"` option to `ITokenProviderOptions.browser`
+  - `"headless"`: Does not open browser, logs authentication URL and waits for manual callback
+  - Ideal for SSH sessions, remote terminals, and environments without display
+  - Differs from `"none"` which immediately rejects (for automated tests)
+  - Updated JSDoc documentation for browser option with all supported values
+
 ## [0.2.3] - 2025-12-19
 
 ### Added

package/README.md

@@ -163,9 +163,13 @@ This package is responsible for:
 - `AuthType` - Auth type: `'jwt' | 'xsuaa' | 'basic'`
 
 ### Token Domain (`token/`)
-- `ITokenProvider` - Token provider interface
+- `ITokenProvider` - Token provider interface (for auth-broker to get tokens from OAuth)
 - `ITokenProviderResult` - Result from token provider
 - `ITokenProviderOptions` - Options for token providers
+- `ITokenRefresher` - Token refresher interface for DI into connections
+  - Created by `AuthBroker.createTokenRefresher(destination)`
+  - Injected into `JwtAbapConnection` to enable automatic token refresh
+  - Methods: `getToken()`, `refreshToken()`
 
 ### Session Domain (`session/`)
 - `ISessionStore` - Session storage interface
@@ -174,10 +178,14 @@ This package is responsible for:
 - `IServiceKeyStore` - Service key storage interface
 
 ### Connection Domain (`connection/`)
-- `IAbapConnection` - Main connection interface for ADT operations
-  - Handles HTTP communication with SAP systems
-  - Manages session headers (stateful/stateless mode via `setSessionType()`)
-  - Note: Token refresh and session state persistence are handled by other packages (e.g., auth-broker)
+- `IAbapConnection` - Minimal connection interface for ADT operations
+  - Consumer-facing methods only: `getBaseUrl()`, `getSessionId()`, `setSessionType()`, `makeAdtRequest()`
+  - Implementation details (auth, CSRF, cookies, token refresh) are encapsulated
+  - For JWT: token refresh handled internally via `ITokenRefresher`
+  - For Basic: no token refresh needed
+- `IAbapConnectionExtended` - Deprecated, for backward compatibility
+  - Extends `IAbapConnection` with: `getConfig()`, `getAuthHeaders()`, `connect()`, `reset()`
+  - Will be removed in next major version
 - `IAbapRequestOptions` - Request options for ADT operations
 
 ### SAP Domain (`sap/`)

package/dist/connection/IAbapConnection.d.ts

@@ -1,17 +1,52 @@
-import type { ISapConfig } from '../sap/ISapConfig';
 import type { IAbapRequestOptions } from './IAbapRequestOptions';
 /**
  * Axios response type - using any to avoid dependency on axios package
  * Consumers should use proper AxiosResponse type from axios
  */
 export type AxiosResponse = any;
+/**
+ * ABAP Connection interface
+ *
+ * Minimal interface for consumers to interact with SAP ADT.
+ * Implementation details (auth, token refresh, CSRF, cookies) are encapsulated.
+ *
+ * For JWT connections, token refresh is handled internally via ITokenRefresher.
+ * For Basic connections, no token refresh is needed.
+ */
 export interface IAbapConnection {
-    getConfig(): ISapConfig;
+    /**
+     * Get base URL of SAP system
+     */
     getBaseUrl(): Promise<string>;
-    getAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * Get current session ID (for stateful connections)
+     */
     getSessionId(): string | null;
+    /**
+     * Set session type for subsequent requests
+     * @param type - "stateful" for persistent session, "stateless" for independent requests
+     */
     setSessionType(type: "stateful" | "stateless"): void;
+    /**
+     * Make ADT request to SAP system
+     *
+     * Handles all auth concerns internally:
+     * - Adds authorization header (Basic or Bearer)
+     * - Manages CSRF token
+     * - Retries on 401/403 with token refresh (JWT only)
+     *
+     * @param options - Request options (url, method, data, etc.)
+     * @returns Promise with Axios response
+     */
     makeAdtRequest(options: IAbapRequestOptions): Promise<AxiosResponse>;
+}
+/**
+ * @deprecated Use IAbapConnection instead. Extended interface kept for backward compatibility.
+ * Will be removed in next major version.
+ */
+export interface IAbapConnectionExtended extends IAbapConnection {
+    getConfig(): any;
+    getAuthHeaders(): Promise<Record<string, string>>;
     connect(): Promise<void>;
     reset(): void;
 }

package/dist/connection/IAbapConnection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/IAbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC9B,SAAS,IAAI,UAAU,CAAC;IACxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAAC;IACrD,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACf"}
+{"version":3,"file":"IAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/IAbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAAC;IAErD;;;;;;;;;;OAUG;IACH,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACtE;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,SAAS,IAAI,GAAG,CAAC;IACjB,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/index.d.ts

@@ -11,13 +11,14 @@ export type { AuthType } from './auth/AuthType';
 export type { ITokenProvider } from './token/ITokenProvider';
 export type { ITokenProviderResult } from './token/ITokenProviderResult';
 export type { ITokenProviderOptions } from './token/ITokenProviderOptions';
+export type { ITokenRefresher } from './token/ITokenRefresher';
 export { TOKEN_PROVIDER_ERROR_CODES } from './token/TokenProviderErrorCodes';
 export type { TokenProviderErrorCode } from './token/TokenProviderErrorCodes';
 export type { ISessionStore } from './session/ISessionStore';
 export type { IServiceKeyStore } from './serviceKey/IServiceKeyStore';
 export { STORE_ERROR_CODES } from './store/StoreErrorCodes';
 export type { StoreErrorCode } from './store/StoreErrorCodes';
-export type { IAbapConnection } from './connection/IAbapConnection';
+export type { IAbapConnection, IAbapConnectionExtended } from './connection/IAbapConnection';
 export type { IAbapRequestOptions } from './connection/IAbapRequestOptions';
 export { NETWORK_ERROR_CODES, isNetworkError } from './connection/NetworkErrors';
 export type { NetworkErrorCode } from './connection/NetworkErrors';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAG9E,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAGvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,cAAc,WAAW,CAAC;AAG1B,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAG9E,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC7F,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAGvE,YAAY,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,cAAc,WAAW,CAAC;AAG1B,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/token/ITokenProviderOptions.d.ts

@@ -8,9 +8,10 @@ import type { ILogger } from '../logging/ILogger';
 export interface ITokenProviderOptions {
     /**
      * Browser type for browser-based authentication
-     * Supported values: "chrome", "edge", "firefox", "system" (default), "none"
-     * - "system": Uses system default browser
-     * - "none": Does not open browser automatically (user must open URL manually)
+     * Supported values: "chrome", "edge", "firefox", "system" (default), "none", "headless"
+     * - "system": Uses system default browser (default)
+     * - "headless": Does not open browser, logs URL and waits for manual callback (for SSH/remote sessions)
+     * - "none": Does not open browser, immediately rejects with error (for automated tests)
      */
     browser?: string;
     /**

package/dist/token/ITokenProviderOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ITokenProviderOptions.d.ts","sourceRoot":"","sources":["../../src/token/ITokenProviderOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"ITokenProviderOptions.d.ts","sourceRoot":"","sources":["../../src/token/ITokenProviderOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/token/ITokenRefresher.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Token Refresher interface
+ *
+ * Provides token management with automatic refresh capability.
+ * Implementations are created by AuthBroker and injected into connections.
+ *
+ * This enables dependency injection of token refresh logic into connections,
+ * allowing connections to focus on making requests while the refresher
+ * handles all auth/token lifecycle concerns.
+ */
+/**
+ * Interface for token refresher
+ *
+ * Created by AuthBroker for a specific destination.
+ * Injected into JwtAbapConnection to enable automatic token refresh.
+ */
+export interface ITokenRefresher {
+    /**
+     * Get current valid token.
+     *
+     * May return cached token if still valid, or refresh if expired.
+     * Implementation decides when to refresh based on token expiration.
+     *
+     * @returns Promise that resolves to valid JWT token
+     */
+    getToken(): Promise<string>;
+    /**
+     * Force refresh token.
+     *
+     * Always obtains new token from provider, regardless of current token validity.
+     * Saves new token to session store (cache).
+     *
+     * Use this when getToken() returned a token that was rejected by server (401/403).
+     *
+     * @returns Promise that resolves to new JWT token
+     */
+    refreshToken(): Promise<string>;
+}
+//# sourceMappingURL=ITokenRefresher.d.ts.map

package/dist/token/ITokenRefresher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITokenRefresher.d.ts","sourceRoot":"","sources":["../../src/token/ITokenRefresher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5B;;;;;;;;;OASG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC"}

package/dist/token/ITokenRefresher.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Token Refresher interface
+ *
+ * Provides token management with automatic refresh capability.
+ * Implementations are created by AuthBroker and injected into connections.
+ *
+ * This enables dependency injection of token refresh logic into connections,
+ * allowing connections to focus on making requests while the refresher
+ * handles all auth/token lifecycle concerns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/interfaces",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Shared interfaces for MCP ABAP ADT packages",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",