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

package/README.md

@@ -2,17 +2,31 @@
 
 [![npm version](https://img.shields.io/npm/v/@sonisoft/now-sdk-ext-core.svg)](https://www.npmjs.com/package/@sonisoft/now-sdk-ext-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 
 A comprehensive TypeScript library that extends the ServiceNow SDK with powerful features for application management, automated testing, log monitoring, and more. Perfect for CI/CD pipelines, development automation, and DevOps workflows.
 
 ## ✨ Features
 
 - 🚀 **Application Management** - Install, upgrade, and manage ServiceNow applications programmatically
+- 🏪 **Store Application Management** - Search, install, and update apps from the ServiceNow Store
 - 🧪 **ATF Test Execution** - Run automated tests and get detailed results
 - 📊 **Real-time Log Monitoring** - Tail ServiceNow logs with two efficient methods
 - 🔄 **AMB (Asynchronous Message Bus)** - WebSocket-based real-time event monitoring
 - 📝 **Background Script Execution** - Execute server-side scripts programmatically
+- 📋 **Scope Management** - Set/get current application scope programmatically
+- 📦 **Update Set Management** - Create, clone, inspect, and manage update sets
+- 🔍 **Code Search** - Search across platform code, apps, and tables
+- 🗄️ **Schema Discovery** - Discover table schemas, explain fields, validate catalogs
+- 📎 **Attachment Management** - Upload, list, and retrieve file attachments
+- ⚡ **Batch Operations** - Bulk create/update with variable substitution and query-based bulk operations
+- 🔧 **Workflow Management** - Create complete workflows programmatically
+- 📌 **Task Operations** - Add comments, assign tasks, resolve/close incidents
+- 🔗 **Script Sync** - Bidirectional sync of scripts between local files and instance
+- 📈 **Aggregate Queries** - COUNT, AVG, MIN, MAX, SUM with GROUP BY via Stats API
+- 🏥 **Instance Health** - Version, cluster, stuck jobs, semaphore monitoring
+- 🗺️ **CMDB Relationships** - Query and traverse CI relationship graphs
+- 🔎 **Instance Discovery** - List tables, scoped apps, store apps, and plugins
 - 🔐 **Authentication** - Seamless integration with ServiceNow CLI authentication
 - 📡 **Table API** - Full CRUD operations on ServiceNow tables
 - 🛠️ **Type-Safe** - Complete TypeScript definitions for all APIs
@@ -25,9 +39,9 @@ npm install @sonisoft/now-sdk-ext-core
 
 ### Prerequisites
 
-- Node.js 14.x or higher
+- Node.js 18.x or higher
 - ServiceNow CLI configured with instance credentials
-- TypeScript 4.x or higher (optional, for TypeScript projects)
+- TypeScript 5.x or higher (optional, for TypeScript projects)
 
 ### ServiceNow CLI Setup
 
@@ -359,29 +373,60 @@ console.log('Return value:', result.result);
 
 - **`ServiceNowInstance`** - Instance connection and configuration
 - **`ServiceNowRequest`** - HTTP request handling with authentication
-- **`TableAPIRequest`** - ServiceNow Table API wrapper
+- **`TableAPIRequest`** - ServiceNow Table API wrapper (CRUD)
 
 ### Application Management
 
-- **`ApplicationManager`** - High-level application management
+- **`ApplicationManager`** - Install, upgrade, and validate applications via batch definitions
 - **`AppRepoApplication`** - App repository operations
-- **`BatchDefinition`** - Batch installation definitions
-- **`CompanyApplications`** - Company application queries
+- **`CompanyApplications`** - Store application search, install, update, and progress tracking
+
+### Scope & Configuration
+
+- **`ScopeManager`** - Set/get current application scope, list and retrieve applications
+- **`UpdateSetManager`** - Create, clone, inspect, move records, and manage update sets
 
 ### Testing & Automation
 
-- **`ATFTestExecutor`** - ATF test execution and monitoring
-- **`BackgroundScriptExecutor`** - Server-side script execution
+- **`ATFTestExecutor`** - ATF test execution and monitoring with progress tracking
+- **`BackgroundScriptExecutor`** - Server-side GlideScript execution
+
+### Code & Schema
+
+- **`CodeSearch`** - Search across platform code by term, app, or table
+- **`SchemaDiscovery`** - Discover table schemas, explain fields, validate catalog items
+
+### Data Operations
+
+- **`AttachmentManager`** - Upload, list, and retrieve file attachments
+- **`BatchOperations`** - Sequential bulk create/update with variable substitution
+- **`QueryBatchOperations`** - Query-based bulk update/delete with dry-run safety
+
+### Workflow & Task
+
+- **`WorkflowManager`** - Create complete workflows with activities, transitions, and conditions
+- **`TaskOperations`** - Add comments, assign tasks, resolve/close incidents, approve changes
+
+### Scripting
+
+- **`ScriptSync`** - Bidirectional sync of Script Includes, Business Rules, and more
 
-### Logging & Monitoring
+### Monitoring & Discovery
 
-- **`SyslogReader`** - Log querying and real-time monitoring
-- **`AMBClient`** - Real-time event subscriptions
+- **`AggregateQuery`** - COUNT, AVG, MIN, MAX, SUM with GROUP BY via Stats API
+- **`InstanceHealth`** - Version, cluster nodes, stuck jobs, semaphores, operational counts
+- **`CMDBRelationships`** - Query direct relationships and traverse CI graphs (BFS)
+- **`InstanceDiscovery`** - List tables, scoped apps, store apps, and plugins
+
+### Logging & Real-time Events
+
+- **`SyslogReader`** - Log querying, formatting, export, and real-time tailing
+- **`AMBClient`** - WebSocket-based real-time event subscriptions
 - **`MessageClientBuilder`** - AMB client configuration
 
 ### Utilities
 
-- **`Logger`** - Winston-based logging
+- **`Logger`** - Winston-based logging with file output
 - **`NowStringUtil`** - String manipulation utilities
 - **`AppUtil`** - Application utility functions
 
@@ -460,14 +505,41 @@ node docs/examples/syslog-tail.mjs your-instance error ./logs/errors.log
 
 Comprehensive documentation is available in the `/docs` directory:
 
+**Getting Started:**
 - **[Getting Started](./docs/GettingStarted.md)** - Setup and basic usage
 - **[API Reference](./docs/APIReference.md)** - Complete API documentation
+- **[Examples](./docs/examples/)** - Working code examples
+
+**Application & Scope Management:**
 - **[Application Manager](./docs/ApplicationManager.md)** - Application management guide
+- **[Store Applications](./docs/CompanyApplications.md)** - Store app search, install, and update
+- **[Scope Manager](./docs/ScopeManager.md)** - Application scope management
+- **[Update Set Manager](./docs/UpdateSetManager.md)** - Update set lifecycle management
+
+**Code, Schema & Search:**
+- **[Code Search](./docs/CodeSearch.md)** - Platform code search
+- **[Schema Discovery](./docs/SchemaDiscovery.md)** - Table schema and field discovery
+
+**Data Operations:**
+- **[Attachment Manager](./docs/AttachmentManager.md)** - File attachment operations
+- **[Batch Operations](./docs/BatchOperations.md)** - Bulk create/update with variable substitution
+- **[Query Batch Operations](./docs/QueryBatchOperations.md)** - Query-based bulk update/delete
+
+**Workflow, Task & Scripting:**
+- **[Workflow Manager](./docs/WorkflowManager.md)** - Programmatic workflow creation
+- **[Task Operations](./docs/TaskOperations.md)** - ITSM task management
+- **[Script Sync](./docs/ScriptSync.md)** - Bidirectional script synchronization
+
+**Monitoring & Discovery:**
+- **[Aggregate Query](./docs/AggregateQuery.md)** - Stats API aggregations
+- **[Instance Health](./docs/InstanceHealth.md)** - Health monitoring
+- **[CMDB Relationships](./docs/CMDBRelationships.md)** - CI relationship graph traversal
+- **[Instance Discovery](./docs/InstanceDiscovery.md)** - Table, app, and plugin discovery
+
+**Testing & Logging:**
 - **[ATF Test Executor](./docs/ATFTestExecutor.md)** - Testing automation
 - **[Syslog Reader](./docs/SyslogReader.md)** - Log monitoring guide
 - **[ChannelAjax Tailing](./docs/SyslogReaderChannelAjax.md)** - Advanced log tailing
-- **[AMB Guide](./docs/AMB_FIX_SUMMARY.md)** - Real-time event monitoring
-- **[Examples](./docs/examples/)** - Working code examples
 
 ## 🔧 Advanced Configuration
 
@@ -559,12 +631,14 @@ try {
 
 ## 📦 Dependencies
 
-- `@servicenow/sdk` - ServiceNow SDK
-- `@servicenow/sdk-cli` - ServiceNow CLI tools
-- `cometd` - WebSocket support for AMB
-- `xml2js` - XML parsing
-- `winston` - Logging
+- `@servicenow/sdk` / `@servicenow/sdk-cli` / `@servicenow/sdk-core` - ServiceNow SDK and CLI tools
 - `axios` - HTTP client
+- `cometd` / `cometd-nodejs-client` - WebSocket support for AMB
+- `winston` - Logging
+- `xml2js` / `fast-xml-parser` - XML parsing
+- `ws` - WebSocket client
+- `zod` - Runtime schema validation
+- `lodash` - Utility functions
 
 ## 🧪 Testing
 
@@ -623,15 +697,10 @@ For issues, questions, or contributions:
 
 - [ ] GraphQL API support
 - [ ] Webhook integration
-- [ ] Enhanced batch operations
-- [ ] Performance metrics
-- [ ] CLI tool package
+- [ ] Performance metrics dashboard
+- [ ] Standalone CLI tool package
 - [ ] Plugin development tools
 
-## 📈 Version History
-
-See [CHANGELOG](./CHANGELOG.md) for version history and release notes.
-
 ---
 
 **Made with ❤️ for the ServiceNow Developer Community**

package/dist/index.d.ts

@@ -29,6 +29,8 @@ export * from './comm/http/ServiceNowProcessorRequest.js';
 export * from './comm/http/ServiceNowRequest.js';
 export * from './comm/http/TableAPIRequest.js';
 export * from './comm/ws/ATFMessageHandler.js';
+export * from './sn/aggregate/AggregateModels.js';
+export * from './sn/aggregate/AggregateQuery.js';
 export * from './sn/amb/AuthenticatedWebSocket.js';
 export * from './sn/application/ApplicationDetailModel.js';
 export * from './sn/application/ApplicationManager.js';
@@ -44,8 +46,16 @@ export * from './sn/attachment/AttachmentManager.js';
 export * from './sn/attachment/AttachmentModels.js';
 export * from './sn/batch/BatchModels.js';
 export * from './sn/batch/BatchOperations.js';
+export * from './sn/batch/QueryBatchModels.js';
+export * from './sn/batch/QueryBatchOperations.js';
+export * from './sn/cmdb/CMDBModels.js';
+export * from './sn/cmdb/CMDBRelationships.js';
 export * from './sn/codesearch/CodeSearch.js';
 export * from './sn/codesearch/CodeSearchModels.js';
+export * from './sn/discovery/DiscoveryModels.js';
+export * from './sn/discovery/InstanceDiscovery.js';
+export * from './sn/health/HealthModels.js';
+export * from './sn/health/InstanceHealth.js';
 export * from './sn/schema/SchemaDiscovery.js';
 export * from './sn/schema/SchemaModels.js';
 export * from './sn/scope/ScopeManager.js';

package/dist/index.js

@@ -29,6 +29,8 @@ export * from './comm/http/ServiceNowProcessorRequest.js';
 export * from './comm/http/ServiceNowRequest.js';
 export * from './comm/http/TableAPIRequest.js';
 export * from './comm/ws/ATFMessageHandler.js';
+export * from './sn/aggregate/AggregateModels.js';
+export * from './sn/aggregate/AggregateQuery.js';
 export * from './sn/amb/AuthenticatedWebSocket.js';
 export * from './sn/application/ApplicationDetailModel.js';
 export * from './sn/application/ApplicationManager.js';
@@ -44,8 +46,16 @@ export * from './sn/attachment/AttachmentManager.js';
 export * from './sn/attachment/AttachmentModels.js';
 export * from './sn/batch/BatchModels.js';
 export * from './sn/batch/BatchOperations.js';
+export * from './sn/batch/QueryBatchModels.js';
+export * from './sn/batch/QueryBatchOperations.js';
+export * from './sn/cmdb/CMDBModels.js';
+export * from './sn/cmdb/CMDBRelationships.js';
 export * from './sn/codesearch/CodeSearch.js';
 export * from './sn/codesearch/CodeSearchModels.js';
+export * from './sn/discovery/DiscoveryModels.js';
+export * from './sn/discovery/InstanceDiscovery.js';
+export * from './sn/health/HealthModels.js';
+export * from './sn/health/InstanceHealth.js';
 export * from './sn/schema/SchemaDiscovery.js';
 export * from './sn/schema/SchemaModels.js';
 export * from './sn/scope/ScopeManager.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wCAAwC,CAAC;AACvD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sCAAsC,CAAC;AACrD,cAAc,qCAAqC,CAAC;AACpD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wCAAwC,CAAC;AACvD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sCAAsC,CAAC;AACrD,cAAc,qCAAqC,CAAC;AACpD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}

package/dist/sn/aggregate/AggregateModels.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Options for an aggregate query against a ServiceNow table.
+ */
+export interface AggregateQueryOptions {
+    /** The table name to aggregate (required) */
+    table: string;
+    /** Encoded query to filter records before aggregation */
+    query?: string;
+    /** When true, includes record count in the result */
+    count?: boolean;
+    /** Field names to compute AVG on */
+    avgFields?: string[];
+    /** Field names to compute MIN on */
+    minFields?: string[];
+    /** Field names to compute MAX on */
+    maxFields?: string[];
+    /** Field names to compute SUM on */
+    sumFields?: string[];
+    /** Field names to GROUP BY */
+    groupBy?: string[];
+    /** HAVING clause for group filtering */
+    having?: string;
+    /** Display value handling: "true", "false", or "all" */
+    displayValue?: "true" | "false" | "all";
+}
+/**
+ * Convenience options for a simple count query.
+ */
+export interface CountQueryOptions {
+    /** The table name to count records from (required) */
+    table: string;
+    /** Encoded query to filter records */
+    query?: string;
+}
+/**
+ * Statistics block returned in the aggregate response.
+ * Keys follow ServiceNow naming: count, avg.{field}, min.{field}, max.{field}, sum.{field}
+ */
+export interface AggregateStats {
+    /** Record count (when count was requested) */
+    count?: string;
+    /** Additional stat fields keyed by "avg.{field}", "min.{field}", etc. */
+    [key: string]: unknown;
+}
+/**
+ * A single group in a grouped aggregate result.
+ */
+export interface AggregateGroupResult {
+    /** The group-by field values */
+    groupby_fields: Array<{
+        field: string;
+        value: string;
+        display_value?: string;
+    }>;
+    /** The stats for this group */
+    stats: AggregateStats;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * Result of an aggregate query (non-grouped).
+ */
+export interface AggregateResult {
+    /** The stats for the entire result set */
+    stats: AggregateStats;
+}
+/**
+ * Result of a grouped aggregate query.
+ */
+export interface GroupedAggregateResult {
+    /** Array of group results */
+    groups: AggregateGroupResult[];
+}
+/**
+ * Response wrapper for non-grouped aggregate queries.
+ * The API returns { result: { stats: { count: "123", ... } } }
+ */
+export interface AggregateResponse {
+    result: {
+        stats: AggregateStats;
+    };
+}
+/**
+ * Response wrapper for grouped aggregate queries.
+ * The API returns { result: [ { groupby_fields: [...], stats: {...} }, ... ] }
+ */
+export interface GroupedAggregateResponse {
+    result: AggregateGroupResult[];
+}

package/dist/sn/aggregate/AggregateModels.js

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

package/dist/sn/aggregate/AggregateModels.js.map

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

package/dist/sn/aggregate/AggregateQuery.d.ts

@@ -0,0 +1,50 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { AggregateQueryOptions, CountQueryOptions, AggregateResult, GroupedAggregateResult } from './AggregateModels.js';
+/**
+ * AggregateQuery provides aggregate operations (COUNT, AVG, MIN, MAX, SUM)
+ * against ServiceNow tables via the Stats API (/api/now/stats/).
+ * Supports GROUP BY for grouped aggregations.
+ */
+export declare class AggregateQuery {
+    private static readonly STATS_API_BASE;
+    private _logger;
+    private _req;
+    private _instance;
+    private _headers;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * Count records matching an optional query on a table.
+     * Convenience method that returns a parsed integer.
+     *
+     * @param options Count query options (table required, query optional)
+     * @returns The number of matching records
+     * @throws Error if table name is empty or the API call fails
+     */
+    count(options: CountQueryOptions): Promise<number>;
+    /**
+     * Run an aggregate query (COUNT, AVG, MIN, MAX, SUM) without grouping.
+     *
+     * @param options Aggregate query options
+     * @returns AggregateResult containing the computed statistics
+     * @throws Error if table name is empty or the API call fails
+     */
+    aggregate(options: AggregateQueryOptions): Promise<AggregateResult>;
+    /**
+     * Run a grouped aggregate query with GROUP BY.
+     *
+     * @param options Aggregate query options (groupBy is required)
+     * @returns GroupedAggregateResult with groups and their stats
+     * @throws Error if table name is empty, groupBy is missing/empty, or the API call fails
+     */
+    groupBy(options: AggregateQueryOptions): Promise<GroupedAggregateResult>;
+    /**
+     * Build query parameters from aggregate options.
+     * @private
+     */
+    private _buildQueryParams;
+    /**
+     * Execute a GET request against the Stats API.
+     * @private
+     */
+    private _executeStatsRequest;
+}

package/dist/sn/aggregate/AggregateQuery.js

@@ -0,0 +1,144 @@
+import { Logger } from "../../util/Logger.js";
+import { ServiceNowRequest } from "../../comm/http/ServiceNowRequest.js";
+/**
+ * AggregateQuery provides aggregate operations (COUNT, AVG, MIN, MAX, SUM)
+ * against ServiceNow tables via the Stats API (/api/now/stats/).
+ * Supports GROUP BY for grouped aggregations.
+ */
+export class AggregateQuery {
+    static STATS_API_BASE = '/api/now/stats/';
+    _logger = new Logger("AggregateQuery");
+    _req;
+    _instance;
+    _headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+    };
+    constructor(instance) {
+        this._instance = instance;
+        this._req = new ServiceNowRequest(instance);
+    }
+    /**
+     * Count records matching an optional query on a table.
+     * Convenience method that returns a parsed integer.
+     *
+     * @param options Count query options (table required, query optional)
+     * @returns The number of matching records
+     * @throws Error if table name is empty or the API call fails
+     */
+    async count(options) {
+        if (!options.table || options.table.trim().length === 0) {
+            throw new Error('Table name is required');
+        }
+        this._logger.info(`Counting records in table: ${options.table}${options.query ? ` with query: ${options.query}` : ''}`);
+        const queryParams = {
+            sysparm_count: 'true'
+        };
+        if (options.query) {
+            queryParams.sysparm_query = options.query;
+        }
+        const response = await this._executeStatsRequest(options.table, queryParams);
+        if (response && response.status === 200 && response.bodyObject?.result?.stats) {
+            const count = parseInt(response.bodyObject.result.stats.count || '0', 10);
+            this._logger.info(`Count result for ${options.table}: ${count}`);
+            return count;
+        }
+        throw new Error(`Failed to count records in table '${options.table}'. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * Run an aggregate query (COUNT, AVG, MIN, MAX, SUM) without grouping.
+     *
+     * @param options Aggregate query options
+     * @returns AggregateResult containing the computed statistics
+     * @throws Error if table name is empty or the API call fails
+     */
+    async aggregate(options) {
+        if (!options.table || options.table.trim().length === 0) {
+            throw new Error('Table name is required');
+        }
+        this._logger.info(`Running aggregate query on table: ${options.table}`);
+        const queryParams = this._buildQueryParams(options);
+        const response = await this._executeStatsRequest(options.table, queryParams);
+        if (response && response.status === 200 && response.bodyObject?.result?.stats) {
+            this._logger.info(`Aggregate query complete for ${options.table}`);
+            return { stats: response.bodyObject.result.stats };
+        }
+        throw new Error(`Failed to run aggregate query on table '${options.table}'. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * Run a grouped aggregate query with GROUP BY.
+     *
+     * @param options Aggregate query options (groupBy is required)
+     * @returns GroupedAggregateResult with groups and their stats
+     * @throws Error if table name is empty, groupBy is missing/empty, or the API call fails
+     */
+    async groupBy(options) {
+        if (!options.table || options.table.trim().length === 0) {
+            throw new Error('Table name is required');
+        }
+        if (!options.groupBy || options.groupBy.length === 0) {
+            throw new Error('groupBy fields are required for grouped aggregation');
+        }
+        this._logger.info(`Running grouped aggregate on table: ${options.table}, groupBy: ${options.groupBy.join(',')}`);
+        const queryParams = this._buildQueryParams(options);
+        const response = await this._executeStatsRequest(options.table, queryParams);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            const groups = Array.isArray(response.bodyObject.result)
+                ? response.bodyObject.result
+                : [];
+            this._logger.info(`Grouped aggregate complete for ${options.table}: ${groups.length} groups`);
+            return { groups };
+        }
+        throw new Error(`Failed to run grouped aggregate on table '${options.table}'. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * Build query parameters from aggregate options.
+     * @private
+     */
+    _buildQueryParams(options) {
+        const params = {};
+        if (options.count) {
+            params.sysparm_count = 'true';
+        }
+        if (options.avgFields && options.avgFields.length > 0) {
+            params.sysparm_avg_fields = options.avgFields.join(',');
+        }
+        if (options.minFields && options.minFields.length > 0) {
+            params.sysparm_min_fields = options.minFields.join(',');
+        }
+        if (options.maxFields && options.maxFields.length > 0) {
+            params.sysparm_max_fields = options.maxFields.join(',');
+        }
+        if (options.sumFields && options.sumFields.length > 0) {
+            params.sysparm_sum_fields = options.sumFields.join(',');
+        }
+        if (options.groupBy && options.groupBy.length > 0) {
+            params.sysparm_group_by = options.groupBy.join(',');
+        }
+        if (options.query) {
+            params.sysparm_query = options.query;
+        }
+        if (options.having) {
+            params.sysparm_having = options.having;
+        }
+        if (options.displayValue) {
+            params.sysparm_display_value = options.displayValue;
+        }
+        return params;
+    }
+    /**
+     * Execute a GET request against the Stats API.
+     * @private
+     */
+    async _executeStatsRequest(tableName, queryParams) {
+        const request = {
+            path: AggregateQuery.STATS_API_BASE + tableName,
+            method: 'get',
+            headers: this._headers,
+            query: queryParams,
+            body: null
+        };
+        return await this._req.executeRequest(request);
+    }
+}
+//# sourceMappingURL=AggregateQuery.js.map

package/dist/sn/aggregate/AggregateQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AggregateQuery.js","sourceRoot":"","sources":["../../../src/sn/aggregate/AggregateQuery.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAYtE;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACf,MAAM,CAAU,cAAc,GAAG,iBAAiB,CAAC;IAEnD,OAAO,GAAW,IAAI,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC/C,IAAI,CAAoB;IACxB,SAAS,CAAqB;IAE9B,QAAQ,GAAW;QACvB,cAAc,EAAE,kBAAkB;QAClC,QAAQ,EAAE,kBAAkB;KAC/B,CAAC;IAEF,YAAmB,QAA4B;QAC3C,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,KAAK,CAAC,OAA0B;QACzC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,8BAA8B,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAExH,MAAM,WAAW,GAA2B;YACxC,aAAa,EAAE,MAAM;SACxB,CAAC;QAEF,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,WAAW,CAAC,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9C,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAoB,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAEhG,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YAC5E,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;YAC1E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC,CAAC;YACjE,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,qCAAqC,OAAO,CAAC,KAAK,cAAc,QAAQ,EAAE,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC;IACrH,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,SAAS,CAAC,OAA8B;QACjD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,qCAAqC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAExE,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAoB,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAEhG,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YAC5E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gCAAgC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;YACnE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACvD,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,2CAA2C,OAAO,CAAC,KAAK,cAAc,QAAQ,EAAE,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC;IAC3H,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAO,CAAC,OAA8B;QAC/C,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QAC3E,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,uCAAuC,OAAO,CAAC,KAAK,cAAc,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEjH,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAA2B,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAEvG,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;YACrE,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;gBACpD,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM;gBAC5B,CAAC,CAAC,EAAE,CAAC;YACT,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kCAAkC,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC;YAC9F,OAAO,EAAE,MAAM,EAAE,CAAC;QACtB,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,OAAO,CAAC,KAAK,cAAc,QAAQ,EAAE,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC;IAC7H,CAAC;IAED;;;OAGG;IACK,iBAAiB,CAAC,OAA8B;QACpD,MAAM,MAAM,GAA2B,EAAE,CAAC;QAE1C,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,CAAC,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxD,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC;QACzC,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;QAC3C,CAAC;QAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,CAAC,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC;QACxD,CAAC;QAED,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,oBAAoB,CAAI,SAAiB,EAAE,WAAmC;QACxF,MAAM,OAAO,GAAgB;YACzB,IAAI,EAAE,cAAc,CAAC,cAAc,GAAG,SAAS;YAC/C,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,IAAI,CAAC,QAAQ;YACtB,KAAK,EAAE,WAAW;YAClB,IAAI,EAAE,IAAI;SACb,CAAC;QAEF,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAI,OAAO,CAAC,CAAC;IACtD,CAAC"}

package/dist/sn/batch/QueryBatchModels.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Options for a query-based batch update operation.
+ */
+export interface QueryUpdateOptions {
+    /** The table to update records in (required) */
+    table: string;
+    /** Encoded query to find matching records (required) */
+    query: string;
+    /** The field data to apply to all matching records (required) */
+    data: Record<string, unknown>;
+    /**
+     * When true, actually executes the update.
+     * When false (default), performs a dry run and returns match count only.
+     */
+    confirm?: boolean;
+    /**
+     * Maximum number of records to update.
+     * Defaults to 200. Maximum allowed: 10000.
+     */
+    limit?: number;
+    /** Optional progress callback invoked periodically */
+    onProgress?: (message: string) => void;
+}
+/**
+ * Options for a query-based batch delete operation.
+ */
+export interface QueryDeleteOptions {
+    /** The table to delete records from (required) */
+    table: string;
+    /** Encoded query to find matching records (required) */
+    query: string;
+    /**
+     * When true, actually executes the delete.
+     * When false (default), performs a dry run and returns match count only.
+     */
+    confirm?: boolean;
+    /**
+     * Maximum number of records to delete.
+     * Defaults to 200. Maximum allowed: 10000.
+     */
+    limit?: number;
+    /** Optional progress callback invoked periodically */
+    onProgress?: (message: string) => void;
+}
+/**
+ * Result of a query-based batch update operation.
+ */
+export interface QueryUpdateResult {
+    /** Whether this was a dry run or live execution */
+    dryRun: boolean;
+    /** Number of records that matched the query */
+    matchCount: number;
+    /** Number of records successfully updated (0 if dry run) */
+    updatedCount: number;
+    /** True if all matched records were updated without error (or if dry run) */
+    success: boolean;
+    /** Details of any errors encountered during execution */
+    errors: Array<{
+        sysId: string;
+        error: string;
+    }>;
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * Result of a query-based batch delete operation.
+ */
+export interface QueryDeleteResult {
+    /** Whether this was a dry run or live execution */
+    dryRun: boolean;
+    /** Number of records that matched the query */
+    matchCount: number;
+    /** Number of records successfully deleted (0 if dry run) */
+    deletedCount: number;
+    /** True if all matched records were deleted without error (or if dry run) */
+    success: boolean;
+    /** Details of any errors encountered during execution */
+    errors: Array<{
+        sysId: string;
+        error: string;
+    }>;
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * Response from table query used to find matching records.
+ */
+export interface QueryMatchResponse {
+    result: Array<{
+        sys_id: string;
+        [key: string]: unknown;
+    }>;
+}

package/dist/sn/batch/QueryBatchModels.js

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