@sonisoft/now-sdk-ext-core 2.4.0 → 2.5.2

package/dist/sn/cmdb/CMDBRelationships.js

@@ -0,0 +1,286 @@
+import { Logger } from "../../util/Logger.js";
+import { TableAPIRequest } from "../../comm/http/TableAPIRequest.js";
+/**
+ * CMDBRelationships provides methods for querying and traversing
+ * CMDB relationship graphs. Supports single-level lookups and
+ * multi-level BFS traversal with configurable depth and direction.
+ */
+export class CMDBRelationships {
+    static CMDB_CI_TABLE = 'cmdb_ci';
+    static CMDB_REL_CI_TABLE = 'cmdb_rel_ci';
+    static MAX_DEPTH = 5;
+    static MAX_NODES = 1000;
+    _logger = new Logger("CMDBRelationships");
+    _tableAPI;
+    _instance;
+    /** Cache for CI records to minimize API calls during traversal */
+    _ciCache = new Map();
+    constructor(instance) {
+        this._instance = instance;
+        this._tableAPI = new TableAPIRequest(instance);
+    }
+    /**
+     * Get direct relationships of a CI (single level).
+     *
+     * @param options Relationship query options
+     * @returns RelationshipsResult with the CI and its direct relationships
+     * @throws Error if ciSysId is empty
+     */
+    async getRelationships(options) {
+        if (!options.ciSysId || options.ciSysId.trim().length === 0) {
+            throw new Error('CI sys_id is required');
+        }
+        const direction = options.direction ?? 'both';
+        const limit = options.limit ?? 100;
+        this._logger.info(`Getting relationships for CI ${options.ciSysId} (direction=${direction})`);
+        // Look up the CI
+        const ci = await this._lookupCI(options.ciSysId);
+        if (!ci) {
+            throw new Error(`CI with sys_id '${options.ciSysId}' not found`);
+        }
+        // Query relationships
+        const relationships = [];
+        if (direction === 'downstream' || direction === 'both') {
+            const downstreamRels = await this._queryRelationships(options.ciSysId, 'parent', limit, options.relationType);
+            for (const rel of downstreamRels) {
+                const childId = this._extractSysId(rel.child);
+                const relatedCI = await this._lookupCI(childId);
+                if (relatedCI) {
+                    relationships.push({
+                        relatedCI,
+                        direction: 'downstream',
+                        typeName: this._extractDisplayValue(rel.type),
+                        relationshipSysId: rel.sys_id
+                    });
+                }
+            }
+        }
+        if (direction === 'upstream' || direction === 'both') {
+            const upstreamRels = await this._queryRelationships(options.ciSysId, 'child', limit, options.relationType);
+            for (const rel of upstreamRels) {
+                const parentId = this._extractSysId(rel.parent);
+                const relatedCI = await this._lookupCI(parentId);
+                if (relatedCI) {
+                    relationships.push({
+                        relatedCI,
+                        direction: 'upstream',
+                        typeName: this._extractDisplayValue(rel.type),
+                        relationshipSysId: rel.sys_id
+                    });
+                }
+            }
+        }
+        this._logger.info(`Found ${relationships.length} relationships for CI ${options.ciSysId}`);
+        return { ci, relationships };
+    }
+    /**
+     * Traverse the CMDB relationship graph using BFS starting from a CI.
+     *
+     * @param options Traversal options
+     * @returns GraphTraversalResult with all nodes, edges, and metadata
+     * @throws Error if ciSysId is empty
+     */
+    async traverseGraph(options) {
+        if (!options.ciSysId || options.ciSysId.trim().length === 0) {
+            throw new Error('CI sys_id is required');
+        }
+        const direction = options.direction ?? 'downstream';
+        const maxDepth = Math.min(options.maxDepth ?? 3, CMDBRelationships.MAX_DEPTH);
+        const maxNodes = Math.min(options.maxNodes ?? 200, CMDBRelationships.MAX_NODES);
+        this._logger.info(`Traversing graph from CI ${options.ciSysId} (direction=${direction}, maxDepth=${maxDepth}, maxNodes=${maxNodes})`);
+        // Clear cache for fresh traversal
+        this._ciCache.clear();
+        // Look up root CI
+        const rootCI = await this._lookupCI(options.ciSysId);
+        if (!rootCI) {
+            throw new Error(`CI with sys_id '${options.ciSysId}' not found`);
+        }
+        const nodes = [];
+        const edges = [];
+        const visited = new Set();
+        const queue = [];
+        let apiCallCount = 0;
+        let truncated = false;
+        let truncationReason;
+        // Initialize BFS
+        visited.add(options.ciSysId);
+        nodes.push({
+            sysId: rootCI.sys_id,
+            name: rootCI.name || '',
+            className: rootCI.sys_class_name || '',
+            depth: 0
+        });
+        queue.push({ sysId: options.ciSysId, depth: 0 });
+        let depthLimited = false;
+        // BFS loop
+        while (queue.length > 0) {
+            const { sysId, depth } = queue.shift();
+            if (depth >= maxDepth) {
+                depthLimited = true;
+                continue;
+            }
+            if (nodes.length >= maxNodes) {
+                truncated = true;
+                truncationReason = `Maximum node limit reached (${maxNodes})`;
+                break;
+            }
+            // Query relationships based on direction
+            const rels = [];
+            if (direction === 'downstream' || direction === 'both') {
+                const downRels = await this._queryRelationships(sysId, 'parent', 100, options.relationType);
+                rels.push(...downRels);
+                apiCallCount++;
+            }
+            if (direction === 'upstream' || direction === 'both') {
+                const upRels = await this._queryRelationships(sysId, 'child', 100, options.relationType);
+                rels.push(...upRels);
+                apiCallCount++;
+            }
+            // Process relationships
+            const newSysIds = [];
+            for (const rel of rels) {
+                const parentId = this._extractSysId(rel.parent);
+                const childId = this._extractSysId(rel.child);
+                const typeName = this._extractDisplayValue(rel.type);
+                // Determine the "other" CI based on current node
+                const relatedId = parentId === sysId ? childId : parentId;
+                edges.push({
+                    parentSysId: parentId,
+                    childSysId: childId,
+                    typeName,
+                    relationshipSysId: rel.sys_id
+                });
+                if (!visited.has(relatedId)) {
+                    visited.add(relatedId);
+                    newSysIds.push(relatedId);
+                }
+            }
+            // Batch-fetch CI details for new nodes
+            if (newSysIds.length > 0) {
+                const ciRecords = await this._batchLookupCIs(newSysIds);
+                apiCallCount++;
+                for (const ciRecord of ciRecords) {
+                    if (nodes.length >= maxNodes) {
+                        truncated = true;
+                        truncationReason = `Maximum node limit reached (${maxNodes})`;
+                        break;
+                    }
+                    nodes.push({
+                        sysId: ciRecord.sys_id,
+                        name: ciRecord.name || '',
+                        className: ciRecord.sys_class_name || '',
+                        depth: depth + 1
+                    });
+                    queue.push({ sysId: ciRecord.sys_id, depth: depth + 1 });
+                }
+            }
+        }
+        if (depthLimited && !truncated) {
+            truncated = true;
+            truncationReason = `Maximum depth reached (${maxDepth})`;
+        }
+        this._logger.info(`Traversal complete: ${nodes.length} nodes, ${edges.length} edges, ${apiCallCount} API calls`);
+        return {
+            rootCI,
+            nodes,
+            edges,
+            apiCallCount,
+            truncated,
+            truncationReason
+        };
+    }
+    /**
+     * Look up a single CI by sys_id. Uses cache when available.
+     * @private
+     */
+    async _lookupCI(sysId) {
+        if (this._ciCache.has(sysId)) {
+            return this._ciCache.get(sysId);
+        }
+        const query = {
+            sysparm_query: `sys_id=${sysId}`,
+            sysparm_limit: 1
+        };
+        const response = await this._tableAPI.get(CMDBRelationships.CMDB_CI_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result && response.bodyObject.result.length > 0) {
+            const ci = response.bodyObject.result[0];
+            this._ciCache.set(sysId, ci);
+            return ci;
+        }
+        return null;
+    }
+    /**
+     * Batch look up multiple CIs by sys_id.
+     * @private
+     */
+    async _batchLookupCIs(sysIds) {
+        // Filter out already cached IDs
+        const uncachedIds = sysIds.filter(id => !this._ciCache.has(id));
+        const results = [];
+        // Return cached items
+        for (const id of sysIds) {
+            if (this._ciCache.has(id)) {
+                results.push(this._ciCache.get(id));
+            }
+        }
+        if (uncachedIds.length === 0) {
+            return results;
+        }
+        // Batch-fetch in chunks of 50
+        for (let i = 0; i < uncachedIds.length; i += 50) {
+            const chunk = uncachedIds.slice(i, i + 50);
+            const query = {
+                sysparm_query: `sys_idIN${chunk.join(',')}`,
+                sysparm_limit: chunk.length
+            };
+            const response = await this._tableAPI.get(CMDBRelationships.CMDB_CI_TABLE, query);
+            if (response && response.status === 200 && response.bodyObject?.result) {
+                for (const ci of response.bodyObject.result) {
+                    this._ciCache.set(ci.sys_id, ci);
+                    results.push(ci);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Query relationships from cmdb_rel_ci.
+     * @private
+     */
+    async _queryRelationships(sysId, role, limit, relationType) {
+        let queryStr = `${role}=${sysId}`;
+        if (relationType) {
+            queryStr += `^type.name=${relationType}`;
+        }
+        const query = {
+            sysparm_query: queryStr,
+            sysparm_limit: limit
+        };
+        const response = await this._tableAPI.get(CMDBRelationships.CMDB_REL_CI_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            return response.bodyObject.result;
+        }
+        return [];
+    }
+    /**
+     * Extract sys_id from a field that may be a string or reference object.
+     * @private
+     */
+    _extractSysId(field) {
+        if (typeof field === 'object' && field !== null) {
+            return field.value;
+        }
+        return field;
+    }
+    /**
+     * Extract display value or value from a field.
+     * @private
+     */
+    _extractDisplayValue(field) {
+        if (typeof field === 'object' && field !== null) {
+            return field.display_value || field.value || '';
+        }
+        return field || '';
+    }
+}
+//# sourceMappingURL=CMDBRelationships.js.map

package/dist/sn/cmdb/CMDBRelationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CMDBRelationships.js","sourceRoot":"","sources":["../../../src/sn/cmdb/CMDBRelationships.ts"],"names":[],"mappings":"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"}

package/dist/sn/discovery/DiscoveryModels.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Options for listing tables on the instance.
+ */
+export interface ListTablesOptions {
+    /** Encoded query to filter tables */
+    query?: string;
+    /** Filter by name prefix (e.g., "cmdb_" to get all CMDB tables) */
+    namePrefix?: string;
+    /** Filter by scope (application scope sys_id or name) */
+    scope?: string;
+    /** Only return extendable tables. Defaults to false. */
+    extendableOnly?: boolean;
+    /** Maximum number of results. Defaults to 100. */
+    limit?: number;
+    /** Offset for pagination. Defaults to 0. */
+    offset?: number;
+    /** Fields to return (maps to sysparm_fields). Defaults to common fields. */
+    fields?: string[];
+}
+/**
+ * Options for listing scoped applications.
+ */
+export interface ListScopedAppsOptions {
+    /** Encoded query to filter applications */
+    query?: string;
+    /** Filter by scope name prefix */
+    namePrefix?: string;
+    /** Only return active applications. Defaults to false. */
+    activeOnly?: boolean;
+    /** Maximum number of results. Defaults to 100. */
+    limit?: number;
+    /** Offset for pagination. Defaults to 0. */
+    offset?: number;
+}
+/**
+ * Options for listing store applications.
+ */
+export interface ListStoreAppsOptions {
+    /** Encoded query to filter store applications */
+    query?: string;
+    /** Filter by name prefix */
+    namePrefix?: string;
+    /** Only return active (installed) applications. Defaults to false. */
+    activeOnly?: boolean;
+    /** Maximum number of results. Defaults to 100. */
+    limit?: number;
+    /** Offset for pagination. Defaults to 0. */
+    offset?: number;
+}
+/**
+ * Options for listing plugins.
+ */
+export interface ListPluginsOptions {
+    /** Encoded query to filter plugins */
+    query?: string;
+    /** Filter by name prefix */
+    namePrefix?: string;
+    /** Only return active plugins. Defaults to false. */
+    activeOnly?: boolean;
+    /** Maximum number of results. Defaults to 100. */
+    limit?: number;
+    /** Offset for pagination. Defaults to 0. */
+    offset?: number;
+}
+/**
+ * A table definition record from sys_db_object.
+ */
+export interface TableDefinition {
+    /** System ID */
+    sys_id: string;
+    /** Table name */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Parent table reference */
+    super_class?: string | {
+        link: string;
+        value: string;
+        display_value?: string;
+    };
+    /** Application scope */
+    sys_scope?: string | {
+        link: string;
+        value: string;
+        display_value?: string;
+    };
+    /** Whether the table is extendable */
+    is_extendable?: string;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * A scoped application record from sys_app.
+ */
+export interface ScopedAppRecord {
+    /** System ID */
+    sys_id: string;
+    /** Application name */
+    name: string;
+    /** Application scope */
+    scope?: string;
+    /** Version */
+    version?: string;
+    /** Whether active */
+    active?: string;
+    /** Vendor */
+    vendor?: string;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * A store application record from sys_store_app.
+ */
+export interface StoreAppRecord {
+    /** System ID */
+    sys_id: string;
+    /** Application name */
+    name: string;
+    /** Application scope */
+    scope?: string;
+    /** Version */
+    version?: string;
+    /** Whether active */
+    active?: string;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * A plugin record from v_plugin.
+ */
+export interface PluginRecord {
+    /** System ID */
+    sys_id: string;
+    /** Plugin ID */
+    id?: string;
+    /** Plugin display name */
+    name?: string;
+    /** Whether active */
+    active?: string;
+    /** Version */
+    version?: string;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/** Response from sys_db_object query. */
+export interface TableDefinitionResponse {
+    result: TableDefinition[];
+}
+/** Response from sys_app query. */
+export interface ScopedAppResponse {
+    result: ScopedAppRecord[];
+}
+/** Response from sys_store_app query. */
+export interface StoreAppResponse {
+    result: StoreAppRecord[];
+}
+/** Response from v_plugin query. */
+export interface PluginResponse {
+    result: PluginRecord[];
+}

package/dist/sn/discovery/DiscoveryModels.js

@@ -0,0 +1,5 @@
+// ============================================================
+// Options Types
+// ============================================================
+export {};
+//# sourceMappingURL=DiscoveryModels.js.map

package/dist/sn/discovery/DiscoveryModels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiscoveryModels.js","sourceRoot":"","sources":["../../../src/sn/discovery/DiscoveryModels.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,gBAAgB;AAChB,+DAA+D"}

package/dist/sn/discovery/InstanceDiscovery.d.ts

@@ -0,0 +1,45 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { ListTablesOptions, ListScopedAppsOptions, ListStoreAppsOptions, ListPluginsOptions, TableDefinition, ScopedAppRecord, StoreAppRecord, PluginRecord } from './DiscoveryModels.js';
+/**
+ * InstanceDiscovery provides methods for discovering what tables,
+ * scoped applications, store applications, and plugins exist on a
+ * ServiceNow instance.
+ */
+export declare class InstanceDiscovery {
+    private static readonly SYS_DB_OBJECT_TABLE;
+    private static readonly SYS_APP_TABLE;
+    private static readonly SYS_STORE_APP_TABLE;
+    private static readonly V_PLUGIN_TABLE;
+    private _logger;
+    private _tableAPI;
+    private _instance;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * List tables on the instance with optional filtering.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of table definitions
+     */
+    listTables(options?: ListTablesOptions): Promise<TableDefinition[]>;
+    /**
+     * List scoped applications on the instance.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of scoped application records
+     */
+    listScopedApps(options?: ListScopedAppsOptions): Promise<ScopedAppRecord[]>;
+    /**
+     * List store applications on the instance.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of store application records
+     */
+    listStoreApps(options?: ListStoreAppsOptions): Promise<StoreAppRecord[]>;
+    /**
+     * List plugins on the instance.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of plugin records
+     */
+    listPlugins(options?: ListPluginsOptions): Promise<PluginRecord[]>;
+}

package/dist/sn/discovery/InstanceDiscovery.js

@@ -0,0 +1,163 @@
+import { Logger } from "../../util/Logger.js";
+import { TableAPIRequest } from "../../comm/http/TableAPIRequest.js";
+/**
+ * InstanceDiscovery provides methods for discovering what tables,
+ * scoped applications, store applications, and plugins exist on a
+ * ServiceNow instance.
+ */
+export class InstanceDiscovery {
+    static SYS_DB_OBJECT_TABLE = 'sys_db_object';
+    static SYS_APP_TABLE = 'sys_app';
+    static SYS_STORE_APP_TABLE = 'sys_store_app';
+    static V_PLUGIN_TABLE = 'v_plugin';
+    _logger = new Logger("InstanceDiscovery");
+    _tableAPI;
+    _instance;
+    constructor(instance) {
+        this._instance = instance;
+        this._tableAPI = new TableAPIRequest(instance);
+    }
+    /**
+     * List tables on the instance with optional filtering.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of table definitions
+     */
+    async listTables(options = {}) {
+        this._logger.info('Listing tables on instance');
+        const queryParts = [];
+        if (options.namePrefix) {
+            queryParts.push(`nameSTARTSWITH${options.namePrefix}`);
+        }
+        if (options.scope) {
+            queryParts.push(`sys_scope=${options.scope}`);
+        }
+        if (options.extendableOnly) {
+            queryParts.push('is_extendable=true');
+        }
+        if (options.query) {
+            queryParts.push(options.query);
+        }
+        const query = {
+            sysparm_limit: options.limit ?? 100
+        };
+        if (options.offset !== undefined && options.offset > 0) {
+            query.sysparm_offset = options.offset;
+        }
+        if (queryParts.length > 0) {
+            query.sysparm_query = queryParts.join('^');
+        }
+        if (options.fields && options.fields.length > 0) {
+            query.sysparm_fields = options.fields.join(',');
+        }
+        const response = await this._tableAPI.get(InstanceDiscovery.SYS_DB_OBJECT_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            this._logger.info(`Found ${response.bodyObject.result.length} tables`);
+            return response.bodyObject.result;
+        }
+        throw new Error(`Failed to list tables. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * List scoped applications on the instance.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of scoped application records
+     */
+    async listScopedApps(options = {}) {
+        this._logger.info('Listing scoped applications');
+        const queryParts = [];
+        if (options.namePrefix) {
+            queryParts.push(`nameSTARTSWITH${options.namePrefix}`);
+        }
+        if (options.activeOnly) {
+            queryParts.push('active=true');
+        }
+        if (options.query) {
+            queryParts.push(options.query);
+        }
+        const query = {
+            sysparm_limit: options.limit ?? 100
+        };
+        if (options.offset !== undefined && options.offset > 0) {
+            query.sysparm_offset = options.offset;
+        }
+        if (queryParts.length > 0) {
+            query.sysparm_query = queryParts.join('^');
+        }
+        const response = await this._tableAPI.get(InstanceDiscovery.SYS_APP_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            this._logger.info(`Found ${response.bodyObject.result.length} scoped applications`);
+            return response.bodyObject.result;
+        }
+        throw new Error(`Failed to list scoped applications. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * List store applications on the instance.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of store application records
+     */
+    async listStoreApps(options = {}) {
+        this._logger.info('Listing store applications');
+        const queryParts = [];
+        if (options.namePrefix) {
+            queryParts.push(`nameSTARTSWITH${options.namePrefix}`);
+        }
+        if (options.activeOnly) {
+            queryParts.push('active=true');
+        }
+        if (options.query) {
+            queryParts.push(options.query);
+        }
+        const query = {
+            sysparm_limit: options.limit ?? 100
+        };
+        if (options.offset !== undefined && options.offset > 0) {
+            query.sysparm_offset = options.offset;
+        }
+        if (queryParts.length > 0) {
+            query.sysparm_query = queryParts.join('^');
+        }
+        const response = await this._tableAPI.get(InstanceDiscovery.SYS_STORE_APP_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            this._logger.info(`Found ${response.bodyObject.result.length} store applications`);
+            return response.bodyObject.result;
+        }
+        throw new Error(`Failed to list store applications. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * List plugins on the instance.
+     *
+     * @param options Filtering and pagination options
+     * @returns Array of plugin records
+     */
+    async listPlugins(options = {}) {
+        this._logger.info('Listing plugins');
+        const queryParts = [];
+        if (options.namePrefix) {
+            queryParts.push(`nameSTARTSWITH${options.namePrefix}`);
+        }
+        if (options.activeOnly) {
+            queryParts.push('active=active');
+        }
+        if (options.query) {
+            queryParts.push(options.query);
+        }
+        const query = {
+            sysparm_limit: options.limit ?? 100
+        };
+        if (options.offset !== undefined && options.offset > 0) {
+            query.sysparm_offset = options.offset;
+        }
+        if (queryParts.length > 0) {
+            query.sysparm_query = queryParts.join('^');
+        }
+        const response = await this._tableAPI.get(InstanceDiscovery.V_PLUGIN_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            this._logger.info(`Found ${response.bodyObject.result.length} plugins`);
+            return response.bodyObject.result;
+        }
+        throw new Error(`Failed to list plugins. Status: ${response?.status ?? 'unknown'}`);
+    }
+}
+//# sourceMappingURL=InstanceDiscovery.js.map