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

package/dist/sn/batch/QueryBatchOperations.js

@@ -0,0 +1,195 @@
+import { Logger } from "../../util/Logger.js";
+import { ServiceNowRequest } from "../../comm/http/ServiceNowRequest.js";
+import { TableAPIRequest } from "../../comm/http/TableAPIRequest.js";
+/**
+ * QueryBatchOperations provides query-based bulk update and delete operations.
+ * Records are found by encoded query, then updated or deleted in bulk.
+ * Includes a dry-run mode (default) for safe previewing before execution.
+ */
+export class QueryBatchOperations {
+    static DEFAULT_LIMIT = 200;
+    static MAX_LIMIT = 10000;
+    _logger = new Logger("QueryBatchOperations");
+    _req;
+    _tableAPI;
+    _instance;
+    _headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+    };
+    constructor(instance) {
+        this._instance = instance;
+        this._req = new ServiceNowRequest(instance);
+        this._tableAPI = new TableAPIRequest(instance);
+    }
+    /**
+     * Find records matching a query and update them with the provided data.
+     * Defaults to dry-run mode (confirm=false) which returns match count without executing.
+     *
+     * @param options Query update options
+     * @returns QueryUpdateResult with match count, update count, and any errors
+     * @throws Error if table, query, or data is empty
+     */
+    async queryUpdate(options) {
+        const startTime = Date.now();
+        if (!options.table || options.table.trim().length === 0) {
+            throw new Error('Table name is required');
+        }
+        if (!options.query || options.query.trim().length === 0) {
+            throw new Error('Query is required');
+        }
+        if (!options.data || Object.keys(options.data).length === 0) {
+            throw new Error('Update data is required and must not be empty');
+        }
+        const limit = Math.min(options.limit ?? QueryBatchOperations.DEFAULT_LIMIT, QueryBatchOperations.MAX_LIMIT);
+        const isDryRun = options.confirm !== true;
+        this._logger.info(`Query update on '${options.table}' with query '${options.query}' (dryRun=${isDryRun}, limit=${limit})`);
+        // Step 1: Find matching records
+        const matchingSysIds = await this._findMatchingRecords(options.table, options.query, limit);
+        const matchCount = matchingSysIds.length;
+        if (options.onProgress) {
+            options.onProgress(`Found ${matchCount} matching records in '${options.table}'`);
+        }
+        // Step 2: Dry run - return count only
+        if (isDryRun) {
+            this._logger.info(`Dry run: ${matchCount} records would be updated in '${options.table}'`);
+            return {
+                dryRun: true,
+                matchCount,
+                updatedCount: 0,
+                success: true,
+                errors: [],
+                executionTimeMs: Date.now() - startTime
+            };
+        }
+        // Step 3: Execute updates
+        const errors = [];
+        let updatedCount = 0;
+        for (let i = 0; i < matchingSysIds.length; i++) {
+            const sysId = matchingSysIds[i];
+            try {
+                const response = await this._tableAPI.put(options.table, sysId, options.data);
+                if (response && response.status === 200) {
+                    updatedCount++;
+                }
+                else {
+                    errors.push({ sysId, error: `Update failed with status: ${response?.status ?? 'unknown'}` });
+                }
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                errors.push({ sysId, error: errorMsg });
+            }
+            if (options.onProgress && (i + 1) % 50 === 0) {
+                options.onProgress(`Updated ${updatedCount}/${matchCount} records (${errors.length} errors)`);
+            }
+        }
+        if (options.onProgress) {
+            options.onProgress(`Update complete: ${updatedCount} updated, ${errors.length} errors`);
+        }
+        return {
+            dryRun: false,
+            matchCount,
+            updatedCount,
+            success: errors.length === 0,
+            errors,
+            executionTimeMs: Date.now() - startTime
+        };
+    }
+    /**
+     * Find records matching a query and delete them.
+     * Defaults to dry-run mode (confirm=false) which returns match count without executing.
+     *
+     * @param options Query delete options
+     * @returns QueryDeleteResult with match count, delete count, and any errors
+     * @throws Error if table or query is empty
+     */
+    async queryDelete(options) {
+        const startTime = Date.now();
+        if (!options.table || options.table.trim().length === 0) {
+            throw new Error('Table name is required');
+        }
+        if (!options.query || options.query.trim().length === 0) {
+            throw new Error('Query is required');
+        }
+        const limit = Math.min(options.limit ?? QueryBatchOperations.DEFAULT_LIMIT, QueryBatchOperations.MAX_LIMIT);
+        const isDryRun = options.confirm !== true;
+        this._logger.info(`Query delete on '${options.table}' with query '${options.query}' (dryRun=${isDryRun}, limit=${limit})`);
+        // Step 1: Find matching records
+        const matchingSysIds = await this._findMatchingRecords(options.table, options.query, limit);
+        const matchCount = matchingSysIds.length;
+        if (options.onProgress) {
+            options.onProgress(`Found ${matchCount} matching records in '${options.table}'`);
+        }
+        // Step 2: Dry run - return count only
+        if (isDryRun) {
+            this._logger.info(`Dry run: ${matchCount} records would be deleted from '${options.table}'`);
+            return {
+                dryRun: true,
+                matchCount,
+                deletedCount: 0,
+                success: true,
+                errors: [],
+                executionTimeMs: Date.now() - startTime
+            };
+        }
+        // Step 3: Execute deletes
+        const errors = [];
+        let deletedCount = 0;
+        for (let i = 0; i < matchingSysIds.length; i++) {
+            const sysId = matchingSysIds[i];
+            try {
+                const request = {
+                    path: `/api/now/table/${options.table}/${sysId}`,
+                    method: 'delete',
+                    headers: this._headers,
+                    query: null,
+                    body: null
+                };
+                const response = await this._req.executeRequest(request);
+                if (response && (response.status === 200 || response.status === 204)) {
+                    deletedCount++;
+                }
+                else {
+                    errors.push({ sysId, error: `Delete failed with status: ${response?.status ?? 'unknown'}` });
+                }
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                errors.push({ sysId, error: errorMsg });
+            }
+            if (options.onProgress && (i + 1) % 50 === 0) {
+                options.onProgress(`Deleted ${deletedCount}/${matchCount} records (${errors.length} errors)`);
+            }
+        }
+        if (options.onProgress) {
+            options.onProgress(`Delete complete: ${deletedCount} deleted, ${errors.length} errors`);
+        }
+        return {
+            dryRun: false,
+            matchCount,
+            deletedCount,
+            success: errors.length === 0,
+            errors,
+            executionTimeMs: Date.now() - startTime
+        };
+    }
+    /**
+     * Find records matching a query and return their sys_ids.
+     * Only fetches sys_id field for efficiency.
+     * @private
+     */
+    async _findMatchingRecords(table, query, limit) {
+        const queryParams = {
+            sysparm_query: query,
+            sysparm_limit: limit,
+            sysparm_fields: 'sys_id'
+        };
+        const response = await this._tableAPI.get(table, queryParams);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            return response.bodyObject.result.map(r => r.sys_id);
+        }
+        throw new Error(`Failed to query records in table '${table}'. Status: ${response?.status ?? 'unknown'}`);
+    }
+}
+//# sourceMappingURL=QueryBatchOperations.js.map

package/dist/sn/batch/QueryBatchOperations.js.map

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

package/dist/sn/cmdb/CMDBModels.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Direction of relationship traversal.
+ */
+export type TraversalDirection = 'upstream' | 'downstream' | 'both';
+/**
+ * Options for getting direct relationships of a CI.
+ */
+export interface GetRelationshipsOptions {
+    /** The sys_id of the CI to get relationships for (required) */
+    ciSysId: string;
+    /** Direction of traversal. Defaults to 'both'. */
+    direction?: TraversalDirection;
+    /** Optional relationship type filter (name from cmdb_rel_type) */
+    relationType?: string;
+    /** Maximum number of relationships to return. Defaults to 100. */
+    limit?: number;
+}
+/**
+ * Options for traversing the CMDB relationship graph.
+ */
+export interface TraverseGraphOptions {
+    /** The sys_id of the starting CI (required) */
+    ciSysId: string;
+    /** Direction of traversal. Defaults to 'downstream'. */
+    direction?: TraversalDirection;
+    /** Maximum traversal depth. Defaults to 3. Max allowed: 5. */
+    maxDepth?: number;
+    /** Optional relationship type filter */
+    relationType?: string;
+    /** Maximum total CIs to visit. Defaults to 200. Max allowed: 1000. */
+    maxNodes?: number;
+}
+/**
+ * A CI record from the CMDB.
+ */
+export interface CMDBCIRecord {
+    /** The system ID */
+    sys_id: string;
+    /** The CI name */
+    name?: string;
+    /** The CI class (table name) */
+    sys_class_name?: string;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * A relationship record from cmdb_rel_ci.
+ */
+export interface CMDBRelationshipRecord {
+    /** The system ID of the relationship */
+    sys_id: string;
+    /** The parent CI sys_id */
+    parent: string | {
+        link: string;
+        value: string;
+        display_value?: string;
+    };
+    /** The child CI sys_id */
+    child: string | {
+        link: string;
+        value: string;
+        display_value?: string;
+    };
+    /** The relationship type */
+    type: string | {
+        link: string;
+        value: string;
+        display_value?: string;
+    };
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * A node in the relationship graph.
+ */
+export interface GraphNode {
+    /** The CI sys_id */
+    sysId: string;
+    /** The CI name */
+    name: string;
+    /** The CI class */
+    className: string;
+    /** Depth from the starting CI (0 = root) */
+    depth: number;
+}
+/**
+ * An edge in the relationship graph.
+ */
+export interface GraphEdge {
+    /** Parent CI sys_id */
+    parentSysId: string;
+    /** Child CI sys_id */
+    childSysId: string;
+    /** Relationship type name */
+    typeName: string;
+    /** Relationship sys_id */
+    relationshipSysId: string;
+}
+/**
+ * Result of getting direct relationships.
+ */
+export interface RelationshipsResult {
+    /** The queried CI */
+    ci: CMDBCIRecord;
+    /** Direct relationships */
+    relationships: Array<{
+        /** The related CI */
+        relatedCI: CMDBCIRecord;
+        /** Direction: 'upstream' (this CI is child) or 'downstream' (this CI is parent) */
+        direction: 'upstream' | 'downstream';
+        /** Relationship type name */
+        typeName: string;
+        /** Relationship record sys_id */
+        relationshipSysId: string;
+    }>;
+}
+/**
+ * Result of a full graph traversal.
+ */
+export interface GraphTraversalResult {
+    /** The starting CI */
+    rootCI: CMDBCIRecord;
+    /** All nodes visited in the graph */
+    nodes: GraphNode[];
+    /** All edges discovered in the graph */
+    edges: GraphEdge[];
+    /** Total number of API calls made */
+    apiCallCount: number;
+    /** Whether the traversal was truncated due to maxDepth or maxNodes */
+    truncated: boolean;
+    /** Reason for truncation if truncated is true */
+    truncationReason?: string;
+}
+/** Response from cmdb_ci query. */
+export interface CMDBCIResponse {
+    result: CMDBCIRecord[];
+}
+/** Response from cmdb_rel_ci query. */
+export interface CMDBRelResponse {
+    result: CMDBRelationshipRecord[];
+}

package/dist/sn/cmdb/CMDBModels.js

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

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

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

package/dist/sn/cmdb/CMDBRelationships.d.ts

@@ -0,0 +1,60 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { GetRelationshipsOptions, TraverseGraphOptions, RelationshipsResult, GraphTraversalResult } from './CMDBModels.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 declare class CMDBRelationships {
+    private static readonly CMDB_CI_TABLE;
+    private static readonly CMDB_REL_CI_TABLE;
+    private static readonly MAX_DEPTH;
+    private static readonly MAX_NODES;
+    private _logger;
+    private _tableAPI;
+    private _instance;
+    /** Cache for CI records to minimize API calls during traversal */
+    private _ciCache;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * 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
+     */
+    getRelationships(options: GetRelationshipsOptions): Promise<RelationshipsResult>;
+    /**
+     * 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
+     */
+    traverseGraph(options: TraverseGraphOptions): Promise<GraphTraversalResult>;
+    /**
+     * Look up a single CI by sys_id. Uses cache when available.
+     * @private
+     */
+    private _lookupCI;
+    /**
+     * Batch look up multiple CIs by sys_id.
+     * @private
+     */
+    private _batchLookupCIs;
+    /**
+     * Query relationships from cmdb_rel_ci.
+     * @private
+     */
+    private _queryRelationships;
+    /**
+     * Extract sys_id from a field that may be a string or reference object.
+     * @private
+     */
+    private _extractSysId;
+    /**
+     * Extract display value or value from a field.
+     * @private
+     */
+    private _extractDisplayValue;
+}