@mcp-abap-adt/interfaces 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.16] - 2025-12-13
+
+### Changed
+- **HTTP timeout docs**: Clarified `timeout` option in `IAdtOperationOptions` to explain behavior and mention `withLongPolling` interplay
+- **VSCode spell checking**: Limited spell checker scope to project files to reduce false positives
+
+## [0.1.15] - 2025-12-12
+
+### Added
+- **Long Polling Support for Read Operations**: Added optional `withLongPolling` parameter to all GET-based read methods
+  - **IAdtObject Interface**:
+    - `read(config, version?, options?)` - Added optional `options?: { withLongPolling?: boolean }` parameter
+    - `readMetadata(config, options?)` - Added optional `options?: { withLongPolling?: boolean }` parameter
+    - `readTransport(config, options?)` - Added optional `options?: { withLongPolling?: boolean }` parameter
+  - **IBuilder Interface** (in `@mcp-abap-adt/adt-clients`):
+    - `read(version?, options?)` - Added optional `options?: { withLongPolling?: boolean }` parameter
+  - **Usage**: When `withLongPolling: true` is specified, the request includes `?withLongPolling=true` query parameter
+    - This allows the server to hold the connection open until the object becomes available or a timeout occurs
+    - Useful after create/activate operations to wait until object is ready for reading
+    - Can replace timeout-based polling in tests and production code
+  - **Example**:
+    ```typescript
+    // Wait for object to become available after creation
+    const domain = await adtDomain.read(
+      { domainName: 'Z_TEST' },
+      'active',
+      { withLongPolling: true }
+    );
+    
+    // Read metadata with long polling
+    const metadata = await adtDomain.readMetadata(
+      { domainName: 'Z_TEST' },
+      { withLongPolling: true }
+    );
+    ```
+
 ## [0.1.14] - 2025-12-19
 
 ### Added
@@ -236,4 +272,3 @@ connection.setSessionState(state);
   - `utils/` - Utility types and interfaces
 
 [0.1.0]: https://github.com/fr0ster/mcp-abap-adt-interfaces/releases/tag/v0.1.0
-

package/README.md

@@ -14,6 +14,7 @@ npm install @mcp-abap-adt/interfaces
 
 This package contains all interfaces organized by domain:
 
+- **`adt/`** - ADT object operations interfaces (IAdtObject, operation options, error codes)
 - **`auth/`** - Core authentication interfaces (configs, auth types)
 - **`token/`** - Token-related interfaces (token provider, results, options)
 - **`session/`** - Session storage interface
@@ -21,7 +22,7 @@ This package contains all interfaces organized by domain:
 - **`connection/`** - Connection interfaces (AbapConnection, request options)
 - **`sap/`** - SAP-specific configuration (SapConfig, SapAuthType)
 - **`storage/`** - Storage interfaces (session storage, state)
-- **`logging/`** - Logging interfaces
+- **`logging/`** - Logging interfaces (ILogger, LogLevel enum)
 - **`validation/`** - Validation interfaces
 - **`utils/`** - Utility types and interfaces
 
@@ -33,6 +34,8 @@ This ensures consistency across all packages and follows TypeScript naming conve
 
 ## Usage
 
+### Basic Imports
+
 ```typescript
 import {
   IAuthorizationConfig,
@@ -46,6 +49,30 @@ import {
 } from '@mcp-abap-adt/interfaces';
 ```
 
+### ADT Object Operations
+
+```typescript
+import {
+  IAdtObject,
+  IAdtOperationOptions,
+  AdtObjectErrorCodes,
+  LogLevel
+} from '@mcp-abap-adt/interfaces';
+
+// Example: Read with long polling
+const domain = await adtDomain.read(
+  { domainName: 'Z_TEST' },
+  'active',
+  { withLongPolling: true } // Wait until object is available
+);
+
+// Example: Read metadata with long polling
+const metadata = await adtDomain.readMetadata(
+  { domainName: 'Z_TEST' },
+  { withLongPolling: true }
+);
+```
+
 ## Responsibilities and Design Principles
 
 ### Core Development Principle
@@ -76,6 +103,24 @@ This package is responsible for:
 
 ## Interface Domains
 
+### ADT Domain (`adt/`)
+- `IAdtObject<TConfig, TReadResult>` - High-level ADT object operations interface
+  - Provides simplified CRUD operations with automatic operation chains, error handling, and resource cleanup
+  - Methods: `validate()`, `create()`, `read()`, `readMetadata()`, `readTransport()`, `update()`, `delete()`, `activate()`, `check()`
+  - All read methods support optional `withLongPolling` parameter for waiting until object becomes available
+  - Supports full operation chains:
+    - Create: validate → create → check → lock → check(inactive) → update → unlock → check → activate
+    - Update: lock → check(inactive) → update → unlock → check → activate
+    - Delete: check(deletion) → delete
+- `IAdtOperationOptions` - Unified options for create and update operations
+  - Fields: `activateOnCreate`, `activateOnUpdate`, `deleteOnFailure`, `sourceCode`, `xmlContent`, `timeout`
+- `AdtObjectErrorCodes` - Error code constants for ADT object operations
+  - Constants: `OBJECT_NOT_FOUND`, `OBJECT_NOT_READY`, `VALIDATION_FAILED`, `CREATE_FAILED`, `UPDATE_FAILED`, `DELETE_FAILED`, `ACTIVATE_FAILED`, `CHECK_FAILED`, `LOCK_FAILED`, `UNLOCK_FAILED`
+- `IAdtObjectState` - Base state interface for ADT object operations
+  - Fields: `validationResponse`, `createResult`, `lockHandle`, `updateResult`, `checkResult`, `unlockResult`, `activateResult`, `deleteResult`, `readResult`, `metadataResult`, `transportResult`, `errors`
+- `IAdtObjectConfig` - Base configuration interface for ADT objects
+  - Common fields: `packageName`, `description`, `transportRequest`
+
 ### Authentication Domain (`auth/`)
 - `IAuthorizationConfig` - Authorization values (UAA credentials, refresh token)
 - `IConnectionConfig` - Connection values (service URL, token, client, language)
@@ -110,6 +155,8 @@ This package is responsible for:
 
 ### Logging Domain (`logging/`)
 - `ILogger` - Logger interface
+- `LogLevel` - Log level enum (`ERROR = 0`, `WARN = 1`, `INFO = 2`, `DEBUG = 3`)
+  - Exported from package root: `import { LogLevel } from '@mcp-abap-adt/interfaces'`
 
 ### Validation Domain (`validation/`)
 - `IValidatedAuthConfig` - Validated authentication configuration

package/dist/adt/IAdtObject.d.ts

@@ -78,13 +78,19 @@ export interface IAdtOperationOptions {
      */
     xmlContent?: string;
     /**
-     * Timeout for operations in milliseconds
+     * HTTP request timeout for operations in milliseconds
      * @default 1000 (1 second)
      *
-     * CRITICAL: Without timeouts, operations may fail due to system not completing commands in time.
+     * Note: This timeout is for HTTP request completion, not for waiting object readiness.
+     * For waiting object readiness after create/update/activate operations, use `withLongPolling: true`
+     * in read operations instead of fixed timeouts.
+     *
+     * The `timeout` parameter controls how long to wait for HTTP responses from the server.
      * Increase timeout for complex operations or slow systems.
      *
      * Example: timeout: 5000 for 5 seconds
+     *
+     * @see withLongPolling - Use long polling for waiting object readiness
      */
     timeout?: number;
 }
@@ -122,18 +128,28 @@ export interface IAdtObject<TConfig, TReadResult = TConfig> {
      *
      * @param config - Object identification (name, etc.)
      * @param version - 'active' or 'inactive'
+     * @param options - Optional read options
+     * @param options.withLongPolling - If true, adds ?withLongPolling=true to wait for object to become available
+     *                                  Useful after create/activate operations to wait until object is ready
      * @returns Object configuration or source code, or undefined if not found
      */
-    read(config: Partial<TConfig>, version?: 'active' | 'inactive'): Promise<TReadResult | undefined>;
+    read(config: Partial<TConfig>, version?: 'active' | 'inactive', options?: {
+        withLongPolling?: boolean;
+    }): Promise<TReadResult | undefined>;
     /**
      * Read object metadata (object characteristics: package, responsible, description, etc.)
      * For objects with source code (Class, Interface, Program), this reads metadata separately from source code.
      * For objects without source code (Domain, DataElement), this may delegate to read() as read() already returns metadata.
      *
      * @param config - Object identification (name, etc.)
+     * @param options - Optional read options
+     * @param options.withLongPolling - If true, adds ?withLongPolling=true to wait for object to become available
+     *                                  Useful after create/activate operations to wait until object is ready
      * @returns State with metadata result
      */
-    readMetadata(config: Partial<TConfig>): Promise<TReadResult>;
+    readMetadata(config: Partial<TConfig>, options?: {
+        withLongPolling?: boolean;
+    }): Promise<TReadResult>;
     /**
      * Update object with full operation chain:
      * lock → check(inactive) → update → unlock → check → activate (optional)
@@ -171,8 +187,13 @@ export interface IAdtObject<TConfig, TReadResult = TConfig> {
     /**
      * Read transport request information for the object
      * @param config - Object identification
+     * @param options - Optional read options
+     * @param options.withLongPolling - If true, adds ?withLongPolling=true to wait for object to become available
+     *                                  Useful after create/activate operations to wait until object is ready
      * @returns State with transport result
      */
-    readTransport(config: Partial<TConfig>): Promise<TReadResult>;
+    readTransport(config: Partial<TConfig>, options?: {
+        withLongPolling?: boolean;
+    }): Promise<TReadResult>;
 }
 //# sourceMappingURL=IAdtObject.d.ts.map

package/dist/adt/IAdtObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IAdtObject.d.ts","sourceRoot":"","sources":["../../src/adt/IAdtObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB;IAC9B,6BAA6B;;IAE7B,iFAAiF;;IAEjF,+BAA+B;;IAE/B,6BAA6B;;IAE7B,2BAA2B;;IAE3B,6BAA6B;;IAE7B,+BAA+B;;IAE/B,0BAA0B;;IAE1B,4BAA4B;;IAE5B,8BAA8B;;CAEtB,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO;IACxD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;;;;;;OASG;IACH,MAAM,CACJ,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;;OAQG;IACH,IAAI,CACF,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAC9B,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEpC;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE7D;;;;;;;;;OASG;IACH,MAAM,CACJ,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEvD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;;;OAMG;IACH,KAAK,CACH,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"IAdtObject.d.ts","sourceRoot":"","sources":["../../src/adt/IAdtObject.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB;IAC9B,6BAA6B;;IAE7B,iFAAiF;;IAEjF,+BAA+B;;IAE/B,6BAA6B;;IAE7B,2BAA2B;;IAE3B,6BAA6B;;IAE7B,+BAA+B;;IAE/B,0BAA0B;;IAE1B,4BAA4B;;IAE5B,8BAA8B;;CAEtB,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO;IACxD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;;;;;;OASG;IACH,MAAM,CACJ,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,IAAI,CACF,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,EAC/B,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEpC;;;;;;;;;;OAUG;IACH,YAAY,CACV,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;;;OASG;IACH,MAAM,CACJ,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEvD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEzD;;;;;;OAMG;IACH,KAAK,CACH,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;;;;;OAOG;IACH,aAAa,CACX,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,WAAW,CAAC,CAAC;CACzB"}

package/package.json

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