@mcp-abap-adt/connection 0.1.13 → 0.1.14

package/README.md

@@ -46,6 +46,58 @@ The package uses a clean separation of concerns:
   - Permission vs auth error detection
   - Suitable for SAP BTP ABAP Environment
 
+## Responsibilities and Design Principles
+
+### Core Development Principle
+
+**Interface-Only Communication**: This package follows a fundamental development principle: **all interactions with external dependencies happen ONLY through interfaces**. The code knows **NOTHING beyond what is defined in the interfaces**.
+
+This means:
+- Does not know about concrete implementation classes from other packages
+- Does not know about internal data structures or methods not defined in interfaces
+- Does not make assumptions about implementation behavior beyond interface contracts
+- Does not access properties or methods not explicitly defined in interfaces
+
+This principle ensures:
+- **Loose coupling**: Connection classes are decoupled from concrete implementations in other packages
+- **Flexibility**: New implementations can be added without modifying connection classes
+- **Testability**: Easy to mock dependencies for testing
+- **Maintainability**: Changes to implementations don't affect connection classes
+
+### Package Responsibilities
+
+This package is responsible for:
+
+1. **HTTP communication with SAP systems**: Makes HTTP requests to SAP ABAP systems via ADT protocol
+2. **Authentication handling**: Supports Basic Auth and JWT/OAuth2 authentication methods
+3. **Session management**: Manages cookies, CSRF tokens, and session state
+4. **Token refresh**: Automatically refreshes expired JWT tokens (for `JwtAbapConnection`)
+5. **Error handling**: Distinguishes between authentication errors and permission errors
+
+#### What This Package Does
+
+- **Provides connection abstraction**: `AbapConnection` interface for interacting with SAP systems
+- **Handles HTTP requests**: Makes requests to SAP ADT endpoints with proper headers and authentication
+- **Manages sessions**: Handles cookies, CSRF tokens, and session state persistence
+- **Refreshes tokens**: Automatically refreshes expired JWT tokens when detected
+- **Validates tokens**: Detects expired tokens by analyzing HTTP response codes (401/403)
+
+#### What This Package Does NOT Do
+
+- **Does NOT obtain tokens**: Token acquisition is handled by `@mcp-abap-adt/auth-providers` and `@mcp-abap-adt/auth-broker`
+- **Does NOT store tokens**: Token storage is handled by `@mcp-abap-adt/auth-stores`
+- **Does NOT orchestrate authentication**: Token lifecycle management is handled by `@mcp-abap-adt/auth-broker`
+- **Does NOT know about destinations**: Destination-based authentication is handled by consumers
+- **Does NOT handle OAuth2 flows**: OAuth2 flows are handled by token providers
+
+### External Dependencies
+
+This package interacts with external packages **ONLY through interfaces**:
+
+- **Logger interface**: Uses `ILogger` interface for logging - does not know about concrete logger implementation
+- **Session storage interface**: Uses `ISessionStorage` interface for session persistence - does not know about concrete storage implementation
+- **No direct dependencies on auth packages**: All token-related operations are handled through configuration (`SapConfig`) passed by consumers
+
 ## Documentation
 
 - 📦 **[Installation Guide](./docs/INSTALLATION.md)** - Setup and installation instructions

package/dist/config/sapConfig.d.ts

@@ -1,15 +1,5 @@
-export type SapAuthType = "basic" | "jwt";
-export interface SapConfig {
-    url: string;
-    client?: string;
-    authType: SapAuthType;
-    username?: string;
-    password?: string;
-    jwtToken?: string;
-    refreshToken?: string;
-    uaaUrl?: string;
-    uaaClientId?: string;
-    uaaClientSecret?: string;
-}
-export declare function sapConfigSignature(config: SapConfig): string;
+import type { ISapConfig, SapAuthType } from '@mcp-abap-adt/interfaces';
+export type { SapAuthType };
+export type SapConfig = ISapConfig;
+export declare function sapConfigSignature(config: ISapConfig): string;
 //# sourceMappingURL=sapConfig.d.ts.map

package/dist/config/sapConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sapConfig.d.ts","sourceRoot":"","sources":["../../src/config/sapConfig.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,KAAK,CAAC;AAE1C,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAmB5D"}
+{"version":3,"file":"sapConfig.d.ts","sourceRoot":"","sources":["../../src/config/sapConfig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGxE,YAAY,EAAE,WAAW,EAAE,CAAC;AAC5B,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AAEnC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAmB7D"}

package/dist/connection/AbapConnection.d.ts

@@ -1,24 +1,4 @@
-import { AxiosResponse } from "axios";
-import { SapConfig } from "../config/sapConfig.js";
-import { SessionState } from "../logger.js";
-export interface AbapRequestOptions {
-    url: string;
-    method: string;
-    timeout: number;
-    data?: any;
-    params?: any;
-    headers?: Record<string, string>;
-}
-export interface AbapConnection {
-    getConfig(): SapConfig;
-    getBaseUrl(): Promise<string>;
-    getAuthHeaders(): Promise<Record<string, string>>;
-    getSessionId(): string | null;
-    setSessionType(type: "stateful" | "stateless"): void;
-    makeAdtRequest(options: AbapRequestOptions): Promise<AxiosResponse>;
-    connect(): Promise<void>;
-    reset(): void;
-    getSessionState(): SessionState | null;
-    setSessionState(state: SessionState): void;
-}
+import type { IAbapRequestOptions, IAbapConnection } from '@mcp-abap-adt/interfaces';
+export type AbapRequestOptions = IAbapRequestOptions;
+export type AbapConnection = IAbapConnection;
 //# sourceMappingURL=AbapConnection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"AbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/AbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,IAAI,SAAS,CAAC;IACvB,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,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,eAAe,IAAI,YAAY,GAAG,IAAI,CAAC;IACvC,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5C"}
+{"version":3,"file":"AbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/AbapConnection.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGrF,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC"}

package/dist/logger.d.ts

@@ -1,67 +1,4 @@
-/**
- * Logger interface for connection layer
- * Allows connection layer to be independent of specific logger implementation
- */
-export interface ILogger {
-    /**
-     * Log informational message
-     */
-    info(message: string, meta?: any): void;
-    /**
-     * Log error message
-     */
-    error(message: string, meta?: any): void;
-    /**
-     * Log warning message
-     */
-    warn(message: string, meta?: any): void;
-    /**
-     * Log debug message
-     */
-    debug(message: string, meta?: any): void;
-    /**
-     * Log CSRF token operations
-     * @param action - Type of CSRF operation: "fetch", "retry", "success", or "error"
-     * @param message - Log message
-     * @param meta - Additional metadata
-     */
-    csrfToken?(action: "fetch" | "retry" | "success" | "error", message: string, meta?: any): void;
-    /**
-     * Log TLS configuration
-     * @param rejectUnauthorized - Whether TLS certificate validation is enabled
-     */
-    tlsConfig?(rejectUnauthorized: boolean): void;
-}
-/**
- * Session state interface for stateful connections
- * Contains cookies and CSRF token that need to be preserved across requests
- */
-export interface SessionState {
-    cookies: string | null;
-    csrfToken: string | null;
-    cookieStore: Record<string, string>;
-}
-/**
- * Interface for storing and retrieving session state
- * Allows connection layer to persist session state (cookies, CSRF token) externally
- */
-export interface ISessionStorage {
-    /**
-     * Save session state for a given session ID
-     * @param sessionId - Unique session identifier
-     * @param state - Session state to save
-     */
-    save(sessionId: string, state: SessionState): Promise<void>;
-    /**
-     * Load session state for a given session ID
-     * @param sessionId - Unique session identifier
-     * @returns Session state or null if not found
-     */
-    load(sessionId: string): Promise<SessionState | null>;
-    /**
-     * Delete session state for a given session ID
-     * @param sessionId - Unique session identifier
-     */
-    delete(sessionId: string): Promise<void>;
-}
+import type { ILogger, ISessionStorage, ISessionState } from '@mcp-abap-adt/interfaces';
+export type { ILogger, ISessionStorage };
+export type SessionState = ISessionState;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAExC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAEzC;;;;;OAKG;IACH,SAAS,CAAC,CACR,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,EAC/C,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,GAAG,GACT,IAAI,CAAC;IAER;;;OAGG;IACH,SAAS,CAAC,CAAC,kBAAkB,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAEtD;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGxF,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;AACzC,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC"}

package/dist/utils/timeouts.d.ts

@@ -1,8 +1,5 @@
-export interface TimeoutConfig {
-    default: number;
-    csrf: number;
-    long: number;
-}
-export declare function getTimeoutConfig(): TimeoutConfig;
+import type { ITimeoutConfig } from '@mcp-abap-adt/interfaces';
+export type TimeoutConfig = ITimeoutConfig;
+export declare function getTimeoutConfig(): ITimeoutConfig;
 export declare function getTimeout(type?: "default" | "csrf" | "long" | number): 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,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAUhD;AAED,wBAAgB,UAAU,CAAC,IAAI,GAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAkB,GAAG,MAAM,CAOzF"}
+{"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,CAUjD;AAED,wBAAgB,UAAU,CAAC,IAAI,GAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAkB,GAAG,MAAM,CAOzF"}

package/dist/utils/tokenRefresh.d.ts

@@ -1,10 +1,8 @@
 /**
  * Token refresh utilities for JWT authentication
  */
-export interface TokenRefreshResult {
-    accessToken: string;
-    refreshToken?: string;
-}
+import type { ITokenRefreshResult } from '@mcp-abap-adt/interfaces';
+export type TokenRefreshResult = ITokenRefreshResult;
 /**
  * Refreshes the access token using refresh token
  * @param refreshToken Refresh token
@@ -13,5 +11,5 @@ export interface TokenRefreshResult {
  * @param clientSecret UAA client secret
  * @returns Promise that resolves to new tokens
  */
-export declare function refreshJwtToken(refreshToken: string, uaaUrl: string, clientId: string, clientSecret: string): Promise<TokenRefreshResult>;
+export declare function refreshJwtToken(refreshToken: string, uaaUrl: string, clientId: string, clientSecret: string): Promise<ITokenRefreshResult>;
 //# sourceMappingURL=tokenRefresh.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tokenRefresh.d.ts","sourceRoot":"","sources":["../../src/utils/tokenRefresh.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAqC7B"}
+{"version":3,"file":"tokenRefresh.d.ts","sourceRoot":"","sources":["../../src/utils/tokenRefresh.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAqC9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -43,6 +43,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@mcp-abap-adt/interfaces": "^0.1.0",
     "axios": "^1.11.0",
     "commander": "^14.0.2",
     "express": "^5.1.0",