@mcp-abap-adt/interfaces-adt 1.0.0

package/dist/auth/ICallbackServer.d.ts

@@ -0,0 +1,139 @@
+import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
+/**
+ * Local callback server used by interactive authorization flows.
+ *
+ * This interface is intentionally domain-agnostic: it describes the lifetime of
+ * a short-lived local listener that receives a redirect, not what the redirect
+ * carries. OAuth authorization codes, OIDC `code` + `state` and SAML
+ * `SAMLResponse` all fit through the same contract, parameterised by result.
+ *
+ * The handle is borrowed: it exists for the duration of the factory's callback,
+ * and the port is released on the first terminal outcome. Releasing the socket
+ * is therefore never a consequence of a wait settling — which is exactly what
+ * lets an abandoned login hold a port for the lifetime of a process.
+ */
+export interface ICallbackServerOptions {
+    /**
+     * Port for the local listener. Must be an integer in 0..65535.
+     *
+     * `0` means "bind an ephemeral port": the handle then reports what the OS
+     * actually gave, and the authorization URL must be built from
+     * `handle.redirectUri` rather than from anything known beforehand. A flow
+     * that assembles its URL before binding — or one whose redirect is
+     * registered with the identity provider, as a SAML ACS always is — cannot
+     * use it, because the redirect would advertise a port nobody is listening on.
+     */
+    readonly port: number;
+    /**
+     * How long to wait for the callback. Mandatory: there is no such thing as
+     * waiting forever, and the absence of this bound is a known way to strand a
+     * port.
+     *
+     * Must satisfy `Number.isFinite(timeoutMs) && timeoutMs > 0 && timeoutMs <=
+     * 2_147_483_647`. The upper bound is Node's rather than this contract's:
+     * `setTimeout` takes a 32-bit signed delay, and a larger value fires after
+     * 1 ms with a `TimeoutOverflowWarning` — so a generous-looking timeout would
+     * end the login almost instantly. Implementations reject such a value rather
+     * than clamping it, because clamping hides the mistake.
+     */
+    readonly timeoutMs: number;
+    /**
+     * External cancellation — "this login is no longer needed". Honoured whether
+     * it fires before the bind, during it, or while waiting for the callback.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Where the transport reports what it did — an ignored request that was not
+     * our redirect, for instance. Absent means silence; never stdout.
+     */
+    readonly logger?: ILogger;
+}
+/**
+ * Borrowed handle on a listening callback server.
+ *
+ * Valid until the scope reaches its first terminal outcome, which may be before
+ * the factory's callback has finished: a timeout or an abort ends the scope
+ * without stopping an already-running callback. Members behave differently once
+ * that has happened, so a still-running body cannot be harmed by touching it:
+ *
+ * - `fail()` becomes a silent no-op and never throws;
+ * - `waitForResult()` returns a rejected promise, never throwing synchronously;
+ * - `port` and `redirectUri` remain readable, being values rather than
+ *   operations.
+ */
+export interface ICallbackServerHandle<TResult> {
+    /** The port actually bound. */
+    readonly port: number;
+    /** Redirect URI the authorization request must use. */
+    readonly redirectUri: string;
+    /**
+     * The result delivered to the callback endpoint.
+     *
+     * Returns the same promise on every call, so it is safe to call repeatedly.
+     * Rejects on timeout, on cancellation, on `fail`, and when the scope ends
+     * while it is still pending — the last of which is why an implementation must
+     * mark the promise handled on creation, so a body that creates it and walks
+     * away cannot raise `unhandledRejection`.
+     *
+     * Receiving a result does **not** end the scope. It hands the value to
+     * whoever is awaiting; the scope ends when the factory's callback returns.
+     */
+    waitForResult(): Promise<TResult>;
+    /**
+     * End the wait with an error — typically because the browser could not be
+     * launched.
+     *
+     * Safe to call at any time, including after the scope has ended, because it
+     * is meant to be used fire-and-forget:
+     *
+     * ```ts
+     * launchBrowser(url).catch((e) => server.fail(e));
+     * ```
+     *
+     * A launcher that rejects after the login has already timed out must not turn
+     * that into a fresh unhandled rejection.
+     */
+    fail(error: Error): void;
+}
+/**
+ * The only way to obtain a callback server.
+ *
+ * There is deliberately no `close` on the handle: closing belongs to the
+ * factory, so it cannot be forgotten.
+ *
+ * The factory settles on the first terminal outcome — the callback returning or
+ * throwing, `fail`, the timeout, or an abort — and only once the listening
+ * socket has been released, so a settled result always means the port is free.
+ * On success it resolves with whatever the callback returned — which need not be
+ * the payload itself, so `transform(await server.waitForResult())` resolves with
+ * the transformed value.
+ *
+ * It does **not** promise to stop the callback: an arbitrary async function
+ * cannot be force-terminated. A failure outcome ends the scope without waiting
+ * for it, and a later settlement from the abandoned body is discarded.
+ *
+ * There are two type parameters, and the split matters:
+ *
+ * - `TResult` is on the alias, because the payload a flow's callback endpoint
+ *   delivers is fixed by that flow. Were it generic per call, a browser-code
+ *   factory would type-check against a caller expecting something it can never
+ *   yield.
+ * - `TReturn` is generic per call, because the scope resolves with whatever the
+ *   callback returned. Tying it to `TResult` would forbid the transformation
+ *   shown above — `transform(await server.waitForResult())` may legitimately
+ *   produce a token, a session, or anything else built from the payload.
+ *
+ * ```ts
+ * const code = await withBrowserCallbackServer(
+ *   { port, timeoutMs, signal },
+ *   async (server) => {
+ *     const waiting = server.waitForResult();
+ *     launchBrowser(buildAuthUrl(server.redirectUri)).catch((e) => server.fail(e));
+ *     return await waiting;
+ *   },
+ * );
+ * // reached only once the port is free — whatever the outcome
+ * ```
+ */
+export type CallbackServerFactory<TResult> = <TReturn>(options: ICallbackServerOptions, use: (server: ICallbackServerHandle<TResult>) => Promise<TReturn>) => Promise<TReturn>;
+//# sourceMappingURL=ICallbackServer.d.ts.map

package/dist/auth/ICallbackServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICallbackServer.d.ts","sourceRoot":"","sources":["../../src/auth/ICallbackServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB,CAAC,OAAO;IAC5C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAElC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,IAAI,CAAC,OAAO,EACnD,OAAO,EAAE,sBAAsB,EAC/B,GAAG,EAAE,CAAC,MAAM,EAAE,qBAAqB,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,KAC9D,OAAO,CAAC,OAAO,CAAC,CAAC"}

package/dist/auth/ICallbackServer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ICertificateMaterialLoader.d.ts

@@ -0,0 +1,7 @@
+import type { ICertificateMaterial } from '@mcp-abap-adt/interfaces-auth';
+import type { ISapConfig } from '../sap/ISapConfig';
+/** Loads client-certificate material from a connection config (file paths, etc.). */
+export interface ICertificateMaterialLoader {
+    load(config: ISapConfig): Promise<ICertificateMaterial>;
+}
+//# sourceMappingURL=ICertificateMaterialLoader.d.ts.map

package/dist/auth/ICertificateMaterialLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICertificateMaterialLoader.d.ts","sourceRoot":"","sources":["../../src/auth/ICertificateMaterialLoader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,qFAAqF;AACrF,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACzD"}

package/dist/auth/ICertificateMaterialLoader.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/IConfig.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration - optional composition of authorization and connection configuration
+ * Can contain either authorization config, or connection config, or both
+ */
+import type { IAuthorizationConfig } from './IAuthorizationConfig';
+import type { IConnectionConfig } from './IConnectionConfig';
+export type IConfig = Partial<IAuthorizationConfig> & Partial<IConnectionConfig>;
+//# sourceMappingURL=IConfig.d.ts.map

package/dist/auth/IConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IConfig.d.ts","sourceRoot":"","sources":["../../src/auth/IConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAAC"}

package/dist/auth/IConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/IConnectionConfig.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Connection configuration - values needed for connecting to services
+ * Returned by stores with actual values (not file paths)
+ */
+export interface IConnectionConfig {
+    /** Service URL (SAP/ABAP/MCP URL) - undefined for XSUAA if not provided */
+    serviceUrl?: string;
+    /** Authorization token (JWT token) - required for JWT auth, optional for basic auth */
+    authorizationToken?: string;
+    /** Username for basic authentication - required for basic auth, optional for JWT auth */
+    username?: string;
+    /** Password for basic authentication - required for basic auth, optional for JWT auth */
+    password?: string;
+    /** Authentication type - 'basic' for on-premise, 'jwt' for cloud */
+    authType?: 'basic' | 'jwt' | 'saml';
+    /** SAP client number (optional, for ABAP/BTP) */
+    sapClient?: string;
+    /** Language (optional, for ABAP/BTP) */
+    language?: string;
+    /** Session cookies for SAML authentication (raw Cookie header value) */
+    sessionCookies?: string;
+}
+//# sourceMappingURL=IConnectionConfig.d.ts.map

package/dist/auth/IConnectionConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IConnectionConfig.d.ts","sourceRoot":"","sources":["../../src/auth/IConnectionConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACpC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/auth/IConnectionConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/connection/CalmService.d.ts

@@ -0,0 +1,3 @@
+export declare const CALM_SERVICES: readonly ["features", "documents", "tasks", "projects", "testManagement", "hierarchy", "analytics", "processMonitoring", "logs"];
+export type CalmService = (typeof CALM_SERVICES)[number];
+//# sourceMappingURL=CalmService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CalmService.d.ts","sourceRoot":"","sources":["../../src/connection/CalmService.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,kIAUhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/connection/CalmService.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CALM_SERVICES = void 0;
+exports.CALM_SERVICES = [
+    'features',
+    'documents',
+    'tasks',
+    'projects',
+    'testManagement',
+    'hierarchy',
+    'analytics',
+    'processMonitoring',
+    'logs',
+];

package/dist/connection/IAbapConnection.d.ts

@@ -0,0 +1,73 @@
+import type { IAbapRequestOptions } from './IAbapRequestOptions';
+/**
+ * Minimal response type for ADT requests.
+ */
+export type IAdtHeaderValue = string | string[] | number | boolean | null | undefined | object;
+/**
+ * The transport frame: status, headers, body — what HTTP or RFC hands back.
+ *
+ * Renamed from `IAdtWireResponse`, which now names the **answer** a member gives
+ * (`adt/IAdtResponse.ts`). This is the wire, and it belongs exactly here: at the
+ * connection boundary, where decision 14 says an envelope is legitimate and
+ * everywhere above it is not.
+ *
+ * The old name was the whole problem in miniature — the same type served as
+ * "what came off the wire" and "what a caller gets", so 94 members answered a
+ * frame and no member could name its result.
+ */
+export interface IAdtWireResponse<T = any, D = any> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Record<string, IAdtHeaderValue> & {
+        location?: string;
+        Location?: string;
+        'content-location'?: IAdtHeaderValue;
+        'Content-Location'?: IAdtHeaderValue;
+        'sap-adt-location'?: IAdtHeaderValue;
+    };
+    config?: D;
+    request?: unknown;
+}
+/**
+ * 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 {
+    /**
+     * Initialize connection: fetch CSRF token and establish session cookies.
+     * Must be called before making any ADT requests.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get base URL of SAP system
+     */
+    getBaseUrl(): Promise<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<T = any, D = any>(options: IAbapRequestOptions): Promise<IAdtWireResponse<T, D>>;
+}
+//# sourceMappingURL=IAbapConnection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/IAbapConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,MAAM,EAAE,GACR,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,MAAM,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG;IAChD,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG;QACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,kBAAkB,CAAC,EAAE,eAAe,CAAC;QACrC,kBAAkB,CAAC,EAAE,eAAe,CAAC;QACrC,kBAAkB,CAAC,EAAE,eAAe,CAAC;KACtC,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;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,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAC7B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACpC"}

package/dist/connection/IAbapConnection.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/connection/IAbapRequestOptions.d.ts

@@ -0,0 +1,9 @@
+export interface IAbapRequestOptions {
+    url: string;
+    method: string;
+    timeout: number;
+    data?: unknown;
+    params?: unknown;
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=IAbapRequestOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IAbapRequestOptions.d.ts","sourceRoot":"","sources":["../../src/connection/IAbapRequestOptions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC"}

package/dist/connection/IAbapRequestOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/connection/ICalmConnection.d.ts

@@ -0,0 +1,29 @@
+import type { CalmService } from './CalmService';
+import type { IAdtWireResponse } from './IAbapConnection';
+import type { ICalmRequestOptions } from './ICalmRequestOptions';
+export type ICalmResponse<T = unknown, D = unknown> = IAdtWireResponse<T, D>;
+/**
+ * Minimal connection interface for SAP Cloud ALM HTTP APIs.
+ *
+ * Implementations encapsulate auth, token refresh, service route resolution,
+ * and request execution so resource clients depend on one narrow contract.
+ */
+export interface ICalmConnection {
+    /**
+     * Initialize the connection and prepare any internal auth state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get the tenant-level base URL.
+     */
+    getBaseUrl(): Promise<string>;
+    /**
+     * Resolve the effective base URL for a concrete Cloud ALM service.
+     */
+    getServiceUrl(service: CalmService): Promise<string>;
+    /**
+     * Execute a request against Cloud ALM.
+     */
+    makeRequest<T = unknown, D = unknown>(options: ICalmRequestOptions): Promise<ICalmResponse<T, D>>;
+}
+//# sourceMappingURL=ICalmConnection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ICalmConnection.d.ts","sourceRoot":"","sources":["../../src/connection/ICalmConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErD;;OAEG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAClC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACjC"}

package/dist/connection/ICalmConnection.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/connection/ICalmRequestOptions.d.ts

@@ -0,0 +1,11 @@
+import type { CalmService } from './CalmService';
+export interface ICalmRequestOptions {
+    url: string;
+    method: string;
+    timeout?: number;
+    service?: CalmService;
+    data?: unknown;
+    params?: unknown;
+    headers?: Record<string, string>;
+}
+//# sourceMappingURL=ICalmRequestOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ICalmRequestOptions.d.ts","sourceRoot":"","sources":["../../src/connection/ICalmRequestOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC"}

package/dist/connection/ICalmRequestOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/connection/IConnectionCapabilities.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Capability atoms for the connection.
+ *
+ * The same shape as the ADT capability atoms, for the same reason:
+ * `IAbapConnection` is the minimum every transport can honour, and this is a
+ * thing only some can. An RFC connection, a batch recorder and a test stub are
+ * all legitimate `IAbapConnection`s that own no HTTP session; making these
+ * methods mandatory would force each of them to implement a lie.
+ *
+ * ADDITIVE to `IAbapConnection`, which is unchanged — an implementation adds the
+ * atom when it genuinely supports it, and a consumer narrows to it.
+ */
+/** Error codes a session-aware connection raises. Match on these, not on messages. */
+export declare const ADT_SESSION_ERROR: {
+    /** No usable session: never connected, or torn down since. */
+    readonly NOT_CONNECTED: "ADT_NOT_CONNECTED";
+    /**
+     * The server put us on a DIFFERENT session than the one we were using.
+     *
+     * Anything locked over the old session is orphaned: the lock handle refers to
+     * a session that no longer exists, so it can be neither used nor released.
+     */
+    readonly SESSION_REPLACED: "ADT_SESSION_REPLACED";
+    /** A transport release is still pending; the session cannot yet be reused. */
+    readonly RELEASE_PENDING: "ADT_RELEASE_PENDING";
+};
+export type AdtSessionErrorCode = (typeof ADT_SESSION_ERROR)[keyof typeof ADT_SESSION_ERROR];
+/**
+ * A connection whose session is owned, observable and explicitly torn down.
+ *
+ * Without this, "is my session still the one I locked over?" is unanswerable
+ * from the consumer's side: a connection can be handed a new server session
+ * silently, and a caller holding a lock has no way to notice.
+ */
+export interface ISessionLifecycleAware {
+    /**
+     * Tells the server this session is finished.
+     *
+     * **It notifies; it does not confirm.** Whether and when the session is
+     * actually freed is the server's affair, and nothing here checks afterwards.
+     * That is why there is no deadline to pass: waiting for the answer to a
+     * message whose answer is not acted on buys the caller nothing, and a
+     * goodbye carries no request timeout by design — so waiting is the one thing
+     * that could make a teardown unbounded.
+     *
+     * Resolves rather than throws, and **always settles**: whatever it could not
+     * finish is the connection's own state, not the caller's problem. A repeat
+     * call performs whatever is still owed.
+     *
+     * **Calling it again does not wait for the goodbye either**, which is what
+     * {@link flushGoodbye} is for. A caller about to reconnect wants both, in
+     * this order:
+     *
+     * ```typescript
+     * await conn.disconnect();
+     * await conn.flushGoodbye();
+     * await conn.connect();
+     * ```
+     *
+     * Without the middle line the next session opens while the previous one's
+     * goodbye is still being assembled, and the server keeps both. With it, the
+     * goodbye is given up to the budget to finish first.
+     *
+     * In-flight requests are NOT waited for. They continue as their caller
+     * arranged and nothing is aborted; their results can no longer affect this
+     * connection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Wait for the goodbye {@link disconnect} sent, within a budget.
+     *
+     * `disconnect()` dispatches the logoff and does not await it, deliberately: a
+     * goodbye carries no request timeout, and a server that never answers must
+     * not hold a teardown open. That is right for teardown and wrong for the one
+     * caller who reconnects — `disconnect()` then `connect()` opens the next
+     * session while the previous one's goodbye is still being assembled, and the
+     * server keeps both.
+     *
+     * Measured on E19 through `@mcp-abap-adt/adt-clients`, whose harness recycled
+     * the session after each test: a new ABAP session every one to two seconds
+     * for the length of a run, none released, each living to its own thirty
+     * minute idle timeout. Turning the recycling off left one session for the
+     * whole run, which is what the harness intended all along.
+     *
+     * **Bounded, and it resolves rather than throws.** The reason not to await
+     * inside `disconnect()` applies here too, so the wait has a budget and gives
+     * up quietly: "the goodbye has not arrived yet" is not a failure of whatever
+     * the caller does next. A goodbye that failed is likewise not the caller's
+     * problem — it is absorbed, not rethrown.
+     *
+     * **So a return is not a confirmation, and not even of dispatch.** Waiting out
+     * the budget resolves the same way as the goodbye finishing, and at that
+     * point the request may not have reached the wire at all — the promise it
+     * waits on covers assembling and sending, not just answering.
+     *
+     * The guarantee is exactly this: **the caller gives the goodbye up to the
+     * budget to finish before carrying on.** If it finishes in time there is no
+     * overlap with the next `connect()`. If it does not, the caller proceeds and
+     * the goodbye stays outstanding for as long as it takes — the budget bounds
+     * the waiting, not the overlap. Whether the server then releases the session
+     * is the server's affair, exactly as it is for `disconnect()`.
+     *
+     * Returns immediately when nothing was dispatched.
+     *
+     * @param timeoutMs how long to wait; an implementation chooses its default.
+     */
+    flushGoodbye(timeoutMs?: number): Promise<void>;
+    /** Whether a caller may start work. False throughout a pending teardown. */
+    isConnected(): boolean;
+    /**
+     * Which server session the connection is on — or `null`, which says nothing
+     * about whether the connection is usable. **Use {@link isConnected} for that.**
+     *
+     * `null` means only that no identity is known, and there are two ways to get
+     * there: no session exists, or the connection is live over a server that
+     * issued no session cookie — some do not. So a live, working connection can
+     * return `null` here, and a consumer that reads `null` as "session lost"
+     * would tear down a connection that was fine.
+     *
+     * What it does identify is the SESSION, not the conversation: a stable
+     * client-side conversation id says nothing about whether the server replaced
+     * the session underneath it, which is precisely the failure this exists to
+     * expose. Compare two readings across an operation to detect a replacement.
+     *
+     * Only a CHANGED value is a replacement. `null` → non-null is an identity
+     * being learned, not a new session: the LOCK response is often the first to
+     * carry a session cookie, and reading that as a replacement would condemn the
+     * operation it just covered.
+     */
+    getSessionIdentity(): string | null;
+}
+/**
+ * A connection whose responses resolve only after a later flush.
+ *
+ * A batch recorder collects requests and settles their promises when the batch
+ * executes. Awaiting one of those promises mid-recording deadlocks: the caller
+ * is blocked inside the very code that would have reached `execute()`.
+ *
+ * Deferral belongs to the connection, not to how a client was configured —
+ * which is why it is declared here rather than passed as an option. A consumer
+ * that wraps a recorder itself, without going through the batch client, still
+ * gets the guard.
+ */
+export interface IDeferredResponseConnection {
+    /** Always `true`. "Sometimes deferred" is not a state a caller could act on. */
+    readonly responsesAreDeferred: true;
+}
+/**
+ * A connection whose ordinary per-request deadline can be suspended.
+ *
+ * A `lock` → write → `unlock` sequence wants to run to completion. Aborting one
+ * of its requests part way ends nothing on the server — the server ends an ABAP
+ * session on its own idle timeout, which this side cannot see — it ends what
+ * this side *knows*: whether the write was applied becomes unanswerable, and
+ * the handle `unlock` needs is lost while the lock lives on in that session.
+ *
+ * Measured on a BTP trial: a `POST /sap/bc/adt/deletion/delete` abandoned at
+ * 45 s was followed by `400 … Session Timed Out or Not Found` carrying a *new*
+ * session cookie. Over HTTP a session is two layers — the ICF one the cookie
+ * addresses and the ABAP one beneath it holding the enqueue locks — and the
+ * abort replaces the first while stranding the second.
+ *
+ * **What this promises, exactly.** Inside a section the connection's ordinary
+ * per-request deadline does not apply. It does **not** promise that no request
+ * can ever be cut short: an implementation is free to keep a far larger ceiling
+ * — `@mcp-abap-adt/connection` raises it to `SAP_TIMEOUT_CRITICAL`, ten minutes
+ * by default — and a socket, a proxy or the process itself ends a request
+ * whatever a contract says. The guarantee is that the short deadline is out of
+ * the way, not that time is.
+ *
+ * Sections nest: the ceiling lifts on the outermost `begin` and ordinary
+ * deadlines resume after the matching `end`.
+ *
+ * Separate from {@link ISessionLifecycleAware} because it answers a different
+ * question: that one is *whose session is this*, this one is *may this request
+ * be cut short*. A batch recorder honours the first and has nothing to protect.
+ */
+export interface ICriticalSection {
+    /**
+     * Enter a section in which the ordinary per-request deadline is suspended.
+     *
+     * Nests. Every call needs its own {@link endCriticalSection}, and the usual
+     * shape is a `try`/`finally` so a throw inside the window still ends it.
+     */
+    beginCriticalSection(): void;
+    /** Leave it. Ordinary deadlines resume when the outermost section ends. */
+    endCriticalSection(): void;
+}
+/**
+ * A connection that can be told what to ask the server to report about itself.
+ *
+ * `X-sap-adt-profiling` asks the server for its own processing time, and
+ * Eclipse sends it on every request. It is a per-connection default: a single
+ * request overrides it through `headers` on the request options, which every
+ * connection already accepts, so this atom exists for the *default* and not for
+ * the one-off.
+ *
+ * `null` asks for nothing. The value is a string rather than an enum because
+ * what a server accepts there is the server's business and grows without this
+ * package: `'server-time'` is what Eclipse asks for and is the sensible
+ * default.
+ *
+ * Worth stating: an implementation is not expected to read the answer back.
+ * The measurement is for whoever is looking at the wire, and being able to turn
+ * it off matters more than being able to consume it.
+ */
+export interface IRequestProfiling {
+    /**
+     * What to ask for on every request from now on, or `null` to ask nothing.
+     *
+     * @param what the `X-sap-adt-profiling` value; `'server-time'` is Eclipse's.
+     */
+    setProfilingRequest(what: string | null): void;
+    /** What this connection is currently asking for. */
+    getProfilingRequest(): string | null;
+}
+//# sourceMappingURL=IConnectionCapabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IConnectionCapabilities.d.ts","sourceRoot":"","sources":["../../src/connection/IConnectionCapabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,sFAAsF;AACtF,eAAO,MAAM,iBAAiB;IAC5B,8DAA8D;;IAE9D;;;;;OAKG;;IAEH,8EAA8E;;CAEtE,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD,4EAA4E;IAC5E,WAAW,IAAI,OAAO,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,oBAAoB,EAAE,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,oBAAoB,IAAI,IAAI,CAAC;IAE7B,2EAA2E;IAC3E,kBAAkB,IAAI,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAE/C,oDAAoD;IACpD,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAAC;CACtC"}

package/dist/connection/IConnectionCapabilities.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Capability atoms for the connection.
+ *
+ * The same shape as the ADT capability atoms, for the same reason:
+ * `IAbapConnection` is the minimum every transport can honour, and this is a
+ * thing only some can. An RFC connection, a batch recorder and a test stub are
+ * all legitimate `IAbapConnection`s that own no HTTP session; making these
+ * methods mandatory would force each of them to implement a lie.
+ *
+ * ADDITIVE to `IAbapConnection`, which is unchanged — an implementation adds the
+ * atom when it genuinely supports it, and a consumer narrows to it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADT_SESSION_ERROR = void 0;
+/** Error codes a session-aware connection raises. Match on these, not on messages. */
+exports.ADT_SESSION_ERROR = {
+    /** No usable session: never connected, or torn down since. */
+    NOT_CONNECTED: 'ADT_NOT_CONNECTED',
+    /**
+     * The server put us on a DIFFERENT session than the one we were using.
+     *
+     * Anything locked over the old session is orphaned: the lock handle refers to
+     * a session that no longer exists, so it can be neither used nor released.
+     */
+    SESSION_REPLACED: 'ADT_SESSION_REPLACED',
+    /** A transport release is still pending; the session cannot yet be reused. */
+    RELEASE_PENDING: 'ADT_RELEASE_PENDING',
+};