catalyst-relay 0.5.0 → 0.5.2

package/README.md

@@ -66,7 +66,8 @@ const [samlClient] = createClient({
     auth: {
         type: 'saml',
         username: 'user@company.com',
-        password: 'pass'
+        password: 'pass',
+        sapUser: 'SAPUSER01'  // Required: SAP username for object attribution
     },
     insecure: true
 });
@@ -124,7 +125,7 @@ curl -X POST http://localhost:3000/login \
   -d '{
     "url": "https://sap-server:443",
     "client": "100",
-    "auth": { "type": "saml", "username": "user@company.com", "password": "pass" }
+    "auth": { "type": "saml", "username": "user@company.com", "password": "pass", "sapUser": "SAPUSER01" }
   }'
 
 # Login with SSO (Kerberos)
@@ -148,6 +149,8 @@ curl -X POST http://localhost:3000/login \
 - Login/logout with session tokens
 - Automatic CSRF token handling and refresh
 - Session expiration with configurable cleanup
+- Automatic session refresh (keepalive) during long operations
+- Manual session refresh via `refreshSession()`
 - Support for multiple concurrent sessions
 
 ### CRAUD Operations
@@ -195,6 +198,7 @@ curl -X POST http://localhost:3000/login \
 |--------|-------------|
 | `login()` | Authenticate and create session |
 | `logout()` | End session |
+| `refreshSession()` | Manually refresh session (keepalive) |
 | `read(objects)` | Batch read with content |
 | `create(object, package, transport?)` | Create new object |
 | `update(object, transport?)` | Update existing object |
@@ -202,7 +206,8 @@ curl -X POST http://localhost:3000/login \
 | `activate(objects)` | Compile and validate |
 | `delete(objects, transport?)` | Remove objects |
 | `getPackages()` | List packages |
-| `getTree(query)` | Browse package tree |
+| `getPackageStats(name)` | Get package metadata and object count |
+| `getTree(query)` | Browse package tree (supports owner filter) |
 | `getTransports(package)` | List transports |
 | `createTransport(config)` | Create transport |
 | `previewData(query)` | Query table/view |
@@ -284,9 +289,11 @@ const [data, error] = await client.previewData({
 |--------|----------|-------------|
 | POST | `/login` | Authenticate and get session ID |
 | DELETE | `/logout` | End session |
+| POST | `/session/refresh` | Refresh session (keepalive) |
 | GET | `/object-config` | List supported object types |
 | GET | `/packages` | List available packages |
-| POST | `/tree` | Browse package tree |
+| GET | `/packages/:name/stats` | Get package metadata and count |
+| POST | `/tree` | Browse package tree (supports owner filter) |
 | GET | `/transports/:package` | List transports |
 | POST | `/transports` | Create transport |
 | POST | `/objects/read` | Batch read objects |
@@ -473,3 +480,7 @@ MIT
 ## Author
 
 Egan Bosch
+
+---
+
+*Last updated: v0.4.5*

package/dist/index.d.mts

@@ -551,7 +551,7 @@ interface ADTClient {
     getTransports(packageName: string): AsyncResult<Transport[]>;
     previewData(query: PreviewSQL): AsyncResult<DataFrame>;
     getDistinctValues(objectName: string, parameters: Parameter[], column: string, objectType?: 'table' | 'view'): AsyncResult<DistinctResult>;
-    countRows(objectName: string, objectType: 'table' | 'view'): AsyncResult<number>;
+    countRows(objectName: string, objectType: 'table' | 'view', parameters?: Parameter[]): AsyncResult<number>;
     search(query: string, types?: string[]): AsyncResult<SearchResult[]>;
     whereUsed(object: ObjectRef): AsyncResult<Dependency[]>;
     createTransport(config: TransportConfig): AsyncResult<string>;
@@ -567,4 +567,18 @@ interface ADTClient {
 
 declare function createClient(config: ClientConfig): Result<ADTClient, Error>;
 
-export { type ADTClient, type ActivationMessage, type ActivationResult, type Aggregation, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, type BetweenFilter, type ClientConfig, type ColumnInfo, type DataFrame, type DataPreviewQuery, type Dependency, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type FolderNode, type ListFilter, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchResult, type Session, type Sorting, type SsoAuthConfig, type SuccessResponse, type Transport, type TransportConfig, type TreeQuery, type TreeResponse, type UpsertResult, buildSQLQuery, createClient, err, ok };
+/**
+ * Logging Utility — Debug logging with activation control
+ *
+ * Logs are silent by default. Call activateLogging() to enable console output.
+ */
+/**
+ * Enable debug logging to console
+ */
+declare function activateLogging(): void;
+/**
+ * Disable debug logging (default state)
+ */
+declare function deactivateLogging(): void;
+
+export { type ADTClient, type ActivationMessage, type ActivationResult, type Aggregation, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, type BetweenFilter, type ClientConfig, type ColumnInfo, type DataFrame, type DataPreviewQuery, type Dependency, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type FolderNode, type ListFilter, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchResult, type Session, type Sorting, type SsoAuthConfig, type SuccessResponse, type Transport, type TransportConfig, type TreeQuery, type TreeResponse, type UpsertResult, activateLogging, buildSQLQuery, createClient, deactivateLogging, err, ok };

package/dist/index.d.ts

@@ -551,7 +551,7 @@ interface ADTClient {
     getTransports(packageName: string): AsyncResult<Transport[]>;
     previewData(query: PreviewSQL): AsyncResult<DataFrame>;
     getDistinctValues(objectName: string, parameters: Parameter[], column: string, objectType?: 'table' | 'view'): AsyncResult<DistinctResult>;
-    countRows(objectName: string, objectType: 'table' | 'view'): AsyncResult<number>;
+    countRows(objectName: string, objectType: 'table' | 'view', parameters?: Parameter[]): AsyncResult<number>;
     search(query: string, types?: string[]): AsyncResult<SearchResult[]>;
     whereUsed(object: ObjectRef): AsyncResult<Dependency[]>;
     createTransport(config: TransportConfig): AsyncResult<string>;
@@ -567,4 +567,18 @@ interface ADTClient {
 
 declare function createClient(config: ClientConfig): Result<ADTClient, Error>;
 
-export { type ADTClient, type ActivationMessage, type ActivationResult, type Aggregation, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, type BetweenFilter, type ClientConfig, type ColumnInfo, type DataFrame, type DataPreviewQuery, type Dependency, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type FolderNode, type ListFilter, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchResult, type Session, type Sorting, type SsoAuthConfig, type SuccessResponse, type Transport, type TransportConfig, type TreeQuery, type TreeResponse, type UpsertResult, buildSQLQuery, createClient, err, ok };
+/**
+ * Logging Utility — Debug logging with activation control
+ *
+ * Logs are silent by default. Call activateLogging() to enable console output.
+ */
+/**
+ * Enable debug logging to console
+ */
+declare function activateLogging(): void;
+/**
+ * Disable debug logging (default state)
+ */
+declare function deactivateLogging(): void;
+
+export { type ADTClient, type ActivationMessage, type ActivationResult, type Aggregation, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type BasicFilter, type BetweenFilter, type ClientConfig, type ColumnInfo, type DataFrame, type DataPreviewQuery, type Dependency, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type ExportableSessionState, type FolderNode, type ListFilter, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectNode, type ObjectRef, type ObjectWithContent, type Package, type PackageNode, type Parameter, type PreviewSQL, type QueryFilter, type Result, type SamlAuthConfig, type SearchResult, type Session, type Sorting, type SsoAuthConfig, type SuccessResponse, type Transport, type TransportConfig, type TreeQuery, type TreeResponse, type UpsertResult, activateLogging, buildSQLQuery, createClient, deactivateLogging, err, ok };

package/dist/index.js

@@ -30,8 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  activateLogging: () => activateLogging,
   buildSQLQuery: () => buildSQLQuery,
   createClient: () => createClient,
+  deactivateLogging: () => deactivateLogging,
   err: () => err,
   ok: () => ok
 });
@@ -871,6 +873,12 @@ function extractCsrfToken(headers) {
 
 // src/core/utils/logging.ts
 var isActive = false;
+function activateLogging() {
+  isActive = true;
+}
+function deactivateLogging() {
+  isActive = false;
+}
 function debug(message) {
   if (isActive) {
     console.log(`[DEBUG] ${message}`);
@@ -915,7 +923,7 @@ async function fetchCsrfToken(state, request4) {
   if (!token) {
     debug("Response headers:");
     response.headers.forEach((value, key) => debug(`  ${key}: ${value.substring(0, 50)}`));
-    return err(new Error("No CSRF token returned in response headers"));
+    return err(new Error("Invalid credentials"));
   }
   state.csrfToken = token;
   debug(`Stored CSRF token in state: ${state.csrfToken?.substring(0, 20)}...`);
@@ -951,7 +959,7 @@ function extractUsername(auth) {
 async function login(state, request4) {
   const [token, tokenErr] = await fetchCsrfToken(state, request4);
   if (tokenErr) {
-    return err(new Error(`Login failed: ${tokenErr.message}`));
+    return err(tokenErr);
   }
   const username = extractUsername(state.config.auth);
   const timeout = getSessionTimeout(state.config.auth.type);
@@ -1093,16 +1101,22 @@ function exportSessionState(ctx, ssoCerts) {
 // src/client/methods/session/importSessionState.ts
 var DEFAULT_REFRESH_INTERVAL2 = 30 * 60 * 1e3;
 async function importSessionState(ctx, state, setSsoCerts) {
+  debug(`importSessionState: starting import`);
   if (state.session.expiresAt <= Date.now()) {
+    debug(`importSessionState: session expired`);
     return err(new Error("Session has expired"));
   }
+  debug(`importSessionState: session expiry OK (expires at ${state.session.expiresAt})`);
   ctx.state.session = state.session;
   ctx.state.csrfToken = state.csrfToken;
+  debug(`importSessionState: restored session and CSRF token`);
   ctx.state.cookies.clear();
   for (const cookie of state.cookies) {
     ctx.state.cookies.set(cookie.name, cookie.value);
   }
+  debug(`importSessionState: restored ${state.cookies.length} cookies`);
   if (state.authType === "sso" && state.ssoCertPaths) {
+    debug(`importSessionState: loading SSO certs from ${state.ssoCertPaths.fullChainPath}`);
     try {
       const fs = await import("fs/promises");
       const [fullChain, key] = await Promise.all([
@@ -1110,32 +1124,52 @@ async function importSessionState(ctx, state, setSsoCerts) {
         fs.readFile(state.ssoCertPaths.keyPath, "utf-8")
       ]);
       setSsoCerts({ cert: fullChain, key });
+      debug(`importSessionState: SSO certs loaded successfully`);
     } catch (certErr) {
+      debug(`importSessionState: SSO cert load failed: ${certErr}`);
       return err(new Error(`Failed to load SSO certificates: ${certErr instanceof Error ? certErr.message : String(certErr)}`));
     }
   }
+  debug(`importSessionState: fetching fresh CSRF token...`);
   const [response, reqErr] = await ctx.request({
     method: "GET",
-    path: "/sap/bc/adt/compatibility/graph"
+    path: "/sap/bc/adt/compatibility/graph",
+    headers: {
+      [CSRF_TOKEN_HEADER]: FETCH_CSRF_TOKEN
+    }
   });
+  debug(`importSessionState: CSRF fetch completed`);
   if (reqErr) {
+    debug(`importSessionState: CSRF fetch error: ${reqErr.message}`);
     ctx.state.session = null;
     ctx.state.csrfToken = null;
     ctx.state.cookies.clear();
     return err(new Error(`Session validation failed: ${reqErr.message}`));
   }
   if (!response.ok) {
+    debug(`importSessionState: CSRF fetch failed with status ${response.status}`);
     ctx.state.session = null;
     ctx.state.csrfToken = null;
     ctx.state.cookies.clear();
     return err(new Error(`Session validation failed with status ${response.status}`));
   }
+  const newToken = extractCsrfToken(response.headers);
+  if (!newToken) {
+    debug(`importSessionState: no CSRF token in response headers`);
+    ctx.state.session = null;
+    ctx.state.csrfToken = null;
+    ctx.state.cookies.clear();
+    return err(new Error("Session validation failed: no CSRF token returned"));
+  }
+  ctx.state.csrfToken = newToken;
+  debug(`importSessionState: new CSRF token obtained: ${newToken.substring(0, 20)}...`);
   const autoRefresh = ctx.state.config.autoRefresh ?? { enabled: true };
   if (autoRefresh.enabled) {
     const interval = autoRefresh.intervalMs ?? DEFAULT_REFRESH_INTERVAL2;
     ctx.startAutoRefresh(interval);
     debug(`Auto-refresh started with ${interval}ms interval (after import)`);
   }
+  debug(`importSessionState: import complete`);
   return ok(true);
 }
 
@@ -1177,6 +1211,14 @@ var OBJECT_CONFIG_MAP = {
     dpEndpoint: "ddic",
     dpParam: "ddicEntityName"
   },
+  "astablds": {
+    endpoint: "ddic/structures",
+    nameSpace: 'xmlns:blue="http://www.sap.com/wbobj/blue"',
+    rootName: "blue:blueSource",
+    type: "STRU/D",
+    label: "Structure" /* STRUCTURE */,
+    extension: "astablds"
+  },
   "asprog": {
     endpoint: "programs/programs",
     nameSpace: 'xmlns:program="http://www.sap.com/adt/programs/programs"',
@@ -2117,8 +2159,8 @@ async function getDistinctValues(client, objectName, parameters, column, _object
 }
 
 // src/core/adt/data_extraction/count.ts
-async function countRows(client, objectName, _objectType) {
-  const sqlQuery = `SELECT COUNT(*) AS row_count FROM ${objectName}`;
+async function countRows(client, objectName, _objectType, parameters = []) {
+  const sqlQuery = `SELECT COUNT(*) AS row_count FROM ${objectName}${parametersToSQLParams(parameters)}`;
   const [dataFrame, error] = await freestyleQuery(client, sqlQuery, 1);
   if (error) {
     return err(new Error(`Row count query failed: ${error.message}`));
@@ -2534,9 +2576,9 @@ async function getDistinctValues2(state, requestor, objectName, parameters, colu
 }
 
 // src/client/methods/preview/countRows.ts
-async function countRows2(state, requestor, objectName, objectType) {
+async function countRows2(state, requestor, objectName, objectType, parameters = []) {
   if (!state.session) return err(new Error("Not logged in"));
-  return countRows(requestor, objectName, objectType);
+  return countRows(requestor, objectName, objectType, parameters);
 }
 
 // src/client/methods/search/search.ts
@@ -2605,6 +2647,7 @@ function createAutoRefresh(getSession, refreshSession3) {
           debug(`Auto-refresh failed: ${refreshErr.message}`);
         }
       }, intervalMs);
+      timer.unref();
     },
     stop() {
       if (timer) {
@@ -2915,8 +2958,8 @@ var ADTClientImpl = class {
   async getDistinctValues(objectName, parameters, column, objectType = "view") {
     return getDistinctValues2(this.state, this.requestor, objectName, parameters, column, objectType);
   }
-  async countRows(objectName, objectType) {
-    return countRows2(this.state, this.requestor, objectName, objectType);
+  async countRows(objectName, objectType, parameters = []) {
+    return countRows2(this.state, this.requestor, objectName, objectType, parameters);
   }
   // --- Search ---
   async search(query, types) {
@@ -2950,8 +2993,10 @@ function createClient(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  activateLogging,
   buildSQLQuery,
   createClient,
+  deactivateLogging,
   err,
   ok
 });