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

package/dist/sn/attachment/AttachmentManager.d.ts

@@ -0,0 +1,32 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { AttachmentRecord, UploadAttachmentOptions, ListAttachmentsOptions } from './AttachmentModels.js';
+/**
+ * AttachmentManager provides methods for uploading, listing, and retrieving
+ * attachments on ServiceNow records via the Attachment API.
+ */
+export declare class AttachmentManager {
+    static readonly ATTACHMENT_API_PATH = "/api/now/attachment";
+    static readonly ATTACHMENT_FILE_API_PATH = "/api/now/attachment/file";
+    static readonly ATTACHMENT_TABLE = "sys_attachment";
+    private _logger;
+    private _req;
+    private _tableAPI;
+    private _instance;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * Upload an attachment to a ServiceNow record.
+     * POST to /api/now/attachment/file with multipart/form-data headers
+     * and query params for table_name, table_sys_id, and file_name.
+     */
+    uploadAttachment(options: UploadAttachmentOptions): Promise<AttachmentRecord>;
+    /**
+     * List attachments for a specific record.
+     * Uses TableAPIRequest.get on sys_attachment with encoded query.
+     */
+    listAttachments(options: ListAttachmentsOptions): Promise<AttachmentRecord[]>;
+    /**
+     * Get a single attachment record by sys_id.
+     * Uses TableAPIRequest.get on sys_attachment with sys_id filter.
+     */
+    getAttachment(sysId: string): Promise<AttachmentRecord>;
+}

package/dist/sn/attachment/AttachmentManager.js

@@ -0,0 +1,87 @@
+import { Logger } from "../../util/Logger.js";
+import { ServiceNowRequest } from "../../comm/http/ServiceNowRequest.js";
+import { TableAPIRequest } from "../../comm/http/TableAPIRequest.js";
+/**
+ * AttachmentManager provides methods for uploading, listing, and retrieving
+ * attachments on ServiceNow records via the Attachment API.
+ */
+export class AttachmentManager {
+    static ATTACHMENT_API_PATH = '/api/now/attachment';
+    static ATTACHMENT_FILE_API_PATH = '/api/now/attachment/file';
+    static ATTACHMENT_TABLE = 'sys_attachment';
+    _logger = new Logger("AttachmentManager");
+    _req;
+    _tableAPI;
+    _instance;
+    constructor(instance) {
+        this._instance = instance;
+        this._req = new ServiceNowRequest(instance);
+        this._tableAPI = new TableAPIRequest(instance);
+    }
+    /**
+     * Upload an attachment to a ServiceNow record.
+     * POST to /api/now/attachment/file with multipart/form-data headers
+     * and query params for table_name, table_sys_id, and file_name.
+     */
+    async uploadAttachment(options) {
+        const { tableName, recordSysId, fileName, contentType, data } = options;
+        this._logger.info(`Uploading attachment '${fileName}' to ${tableName}/${recordSysId}`);
+        const query = {
+            table_name: tableName,
+            table_sys_id: recordSysId,
+            file_name: fileName
+        };
+        const request = {
+            path: AttachmentManager.ATTACHMENT_FILE_API_PATH,
+            method: 'POST',
+            headers: {
+                'Content-Type': contentType,
+                'Accept': 'application/json'
+            },
+            query: query,
+            body: data
+        };
+        const response = await this._req.post(request);
+        if (response && (response.status === 200 || response.status === 201) && response.bodyObject?.result) {
+            this._logger.info(`Successfully uploaded attachment '${fileName}' with sys_id: ${response.bodyObject.result.sys_id}`);
+            return response.bodyObject.result;
+        }
+        throw new Error(`Failed to upload attachment '${fileName}' to ${tableName}/${recordSysId}. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * List attachments for a specific record.
+     * Uses TableAPIRequest.get on sys_attachment with encoded query.
+     */
+    async listAttachments(options) {
+        const { tableName, recordSysId, limit = 100 } = options;
+        this._logger.info(`Listing attachments for ${tableName}/${recordSysId}`);
+        const query = {
+            sysparm_query: `table_name=${tableName}^table_sys_id=${recordSysId}`,
+            sysparm_limit: limit
+        };
+        const response = await this._tableAPI.get(AttachmentManager.ATTACHMENT_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result) {
+            this._logger.info(`Found ${response.bodyObject.result.length} attachments`);
+            return response.bodyObject.result;
+        }
+        throw new Error(`Failed to list attachments for ${tableName}/${recordSysId}. Status: ${response?.status ?? 'unknown'}`);
+    }
+    /**
+     * Get a single attachment record by sys_id.
+     * Uses TableAPIRequest.get on sys_attachment with sys_id filter.
+     */
+    async getAttachment(sysId) {
+        this._logger.info(`Getting attachment with sys_id: ${sysId}`);
+        const query = {
+            sysparm_query: `sys_id=${sysId}`,
+            sysparm_limit: 1
+        };
+        const response = await this._tableAPI.get(AttachmentManager.ATTACHMENT_TABLE, query);
+        if (response && response.status === 200 && response.bodyObject?.result && response.bodyObject.result.length > 0) {
+            this._logger.info(`Found attachment: ${response.bodyObject.result[0].file_name}`);
+            return response.bodyObject.result[0];
+        }
+        throw new Error(`Attachment with sys_id '${sysId}' not found. Status: ${response?.status ?? 'unknown'}`);
+    }
+}
+//# sourceMappingURL=AttachmentManager.js.map

package/dist/sn/attachment/AttachmentManager.js.map

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

package/dist/sn/attachment/AttachmentModels.d.ts

@@ -0,0 +1,28 @@
+export interface AttachmentRecord {
+    sys_id: string;
+    file_name: string;
+    table_name: string;
+    table_sys_id: string;
+    content_type: string;
+    size_bytes?: string;
+    sys_created_on?: string;
+    [key: string]: unknown;
+}
+export interface UploadAttachmentOptions {
+    tableName: string;
+    recordSysId: string;
+    fileName: string;
+    contentType: string;
+    data: Buffer | string;
+}
+export interface ListAttachmentsOptions {
+    tableName: string;
+    recordSysId: string;
+    limit?: number;
+}
+export interface AttachmentResponse {
+    result: AttachmentRecord[];
+}
+export interface AttachmentSingleResponse {
+    result: AttachmentRecord;
+}

package/dist/sn/attachment/AttachmentModels.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AttachmentModels.js.map

package/dist/sn/attachment/AttachmentModels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttachmentModels.js","sourceRoot":"","sources":["../../../src/sn/attachment/AttachmentModels.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,90 @@
+/**
+ * Models for batch operations against ServiceNow tables.
+ */
+/**
+ * A single create operation within a batch.
+ */
+export interface BatchCreateOperation {
+    /** The target table name (e.g., "incident", "sys_user") */
+    table: string;
+    /** The field data to create the record with */
+    data: Record<string, unknown>;
+    /**
+     * Optional key to save the resulting sys_id under.
+     * Other operations can reference this via ${saveAs} in their data values.
+     */
+    saveAs?: string;
+}
+/**
+ * Options for a batch create operation.
+ */
+export interface BatchCreateOptions {
+    /** The ordered list of create operations to execute */
+    operations: BatchCreateOperation[];
+    /**
+     * When true (default), stops on first error (transactional behavior).
+     * When false, continues past errors.
+     */
+    transaction?: boolean;
+    /** Optional progress callback invoked after each operation */
+    onProgress?: (message: string) => void;
+}
+/**
+ * Result of a batch create operation.
+ */
+export interface BatchCreateResult {
+    /** True if all operations completed without error */
+    success: boolean;
+    /** Number of records successfully created */
+    createdCount: number;
+    /** Map of saveAs keys to their created sys_ids */
+    sysIds: Record<string, string>;
+    /** Details of any errors encountered */
+    errors: Array<{
+        operationIndex: number;
+        table: string;
+        error: string;
+    }>;
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * A single update operation within a batch.
+ */
+export interface BatchUpdateOperation {
+    /** The target table name */
+    table: string;
+    /** The sys_id of the record to update */
+    sysId: string;
+    /** The field data to update */
+    data: Record<string, unknown>;
+}
+/**
+ * Options for a batch update operation.
+ */
+export interface BatchUpdateOptions {
+    /** The ordered list of update operations to execute */
+    updates: BatchUpdateOperation[];
+    /** When true, stops on first error. Defaults to false. */
+    stopOnError?: boolean;
+    /** Optional progress callback invoked after each operation */
+    onProgress?: (message: string) => void;
+}
+/**
+ * Result of a batch update operation.
+ */
+export interface BatchUpdateResult {
+    /** True if all updates completed without error */
+    success: boolean;
+    /** Number of records successfully updated */
+    updatedCount: number;
+    /** Details of any errors encountered */
+    errors: Array<{
+        updateIndex: number;
+        table: string;
+        sysId: string;
+        error: string;
+    }>;
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}

package/dist/sn/batch/BatchModels.js

@@ -0,0 +1,5 @@
+/**
+ * Models for batch operations against ServiceNow tables.
+ */
+export {};
+//# sourceMappingURL=BatchModels.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BatchModels.js","sourceRoot":"","sources":["../../../src/sn/batch/BatchModels.ts"],"names":[],"mappings":"AAAA;;GAEG"}

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

@@ -0,0 +1,40 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { BatchCreateOptions, BatchCreateResult, BatchUpdateOptions, BatchUpdateResult } from './BatchModels.js';
+/**
+ * Provides batch create and update operations against ServiceNow tables.
+ * Operations are executed sequentially, with optional transactional (stop-on-error) behavior
+ * and variable reference resolution between operations.
+ */
+export declare class BatchOperations {
+    private _logger;
+    private _req;
+    private _tableAPI;
+    private _instance;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * Execute a batch of create operations sequentially.
+     * Supports variable references: if an operation has saveAs="myKey", later operations
+     * can reference ${myKey} in their data values to substitute the created sys_id.
+     *
+     * @param options Batch create options including operations list and transaction flag
+     * @returns BatchCreateResult with counts, sys_ids, errors, and timing
+     */
+    batchCreate(options: BatchCreateOptions): Promise<BatchCreateResult>;
+    /**
+     * Execute a batch of update operations sequentially.
+     *
+     * @param options Batch update options including updates list and stopOnError flag
+     * @returns BatchUpdateResult with counts, errors, and timing
+     */
+    batchUpdate(options: BatchUpdateOptions): Promise<BatchUpdateResult>;
+    /**
+     * Resolve ${variable} references in data values using the sysIds map.
+     * Serializes the data to JSON, replaces all ${key} patterns with the
+     * corresponding sys_id value, then deserializes back.
+     *
+     * @param data The record data that may contain variable references
+     * @param sysIds Map of variable names to sys_id values
+     * @returns A new data object with all references resolved
+     */
+    private resolveVariableReferences;
+}

package/dist/sn/batch/BatchOperations.js

@@ -0,0 +1,169 @@
+import { Logger } from "../../util/Logger.js";
+import { ServiceNowRequest } from "../../comm/http/ServiceNowRequest.js";
+import { TableAPIRequest } from "../../comm/http/TableAPIRequest.js";
+/**
+ * Provides batch create and update operations against ServiceNow tables.
+ * Operations are executed sequentially, with optional transactional (stop-on-error) behavior
+ * and variable reference resolution between operations.
+ */
+export class BatchOperations {
+    _logger = new Logger("BatchOperations");
+    _req;
+    _tableAPI;
+    _instance;
+    constructor(instance) {
+        this._instance = instance;
+        this._req = new ServiceNowRequest(instance);
+        this._tableAPI = new TableAPIRequest(instance);
+    }
+    /**
+     * Execute a batch of create operations sequentially.
+     * Supports variable references: if an operation has saveAs="myKey", later operations
+     * can reference ${myKey} in their data values to substitute the created sys_id.
+     *
+     * @param options Batch create options including operations list and transaction flag
+     * @returns BatchCreateResult with counts, sys_ids, errors, and timing
+     */
+    async batchCreate(options) {
+        const startTime = Date.now();
+        const transaction = options.transaction !== undefined ? options.transaction : true;
+        const sysIds = {};
+        const errors = [];
+        let createdCount = 0;
+        this._logger.info(`Starting batch create with ${options.operations.length} operations (transaction=${transaction})`);
+        for (let i = 0; i < options.operations.length; i++) {
+            const op = options.operations[i];
+            try {
+                // Resolve variable references in the data using previously saved sys_ids
+                const resolvedData = this.resolveVariableReferences(op.data, sysIds);
+                if (options.onProgress) {
+                    options.onProgress(`Creating record ${i + 1}/${options.operations.length} in table '${op.table}'`);
+                }
+                this._logger.info(`Batch create [${i + 1}/${options.operations.length}]: POST to '${op.table}'`);
+                const response = await this._tableAPI.post(op.table, {}, resolvedData);
+                if (response && (response.status === 200 || response.status === 201) && response.bodyObject?.result?.sys_id) {
+                    const createdSysId = response.bodyObject.result.sys_id;
+                    createdCount++;
+                    if (op.saveAs) {
+                        sysIds[op.saveAs] = createdSysId;
+                    }
+                    this._logger.info(`Batch create [${i + 1}]: Created sys_id=${createdSysId} in '${op.table}'`);
+                }
+                else {
+                    const errorMsg = `Failed to create record in '${op.table}'. Status: ${response?.status ?? 'unknown'}`;
+                    this._logger.error(errorMsg);
+                    errors.push({ operationIndex: i, table: op.table, error: errorMsg });
+                    if (transaction) {
+                        if (options.onProgress) {
+                            options.onProgress(`Stopping batch: error at operation ${i + 1}`);
+                        }
+                        break;
+                    }
+                }
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                this._logger.error(`Batch create [${i + 1}] exception: ${errorMsg}`);
+                errors.push({ operationIndex: i, table: op.table, error: errorMsg });
+                if (transaction) {
+                    if (options.onProgress) {
+                        options.onProgress(`Stopping batch: error at operation ${i + 1}`);
+                    }
+                    break;
+                }
+            }
+        }
+        const executionTimeMs = Date.now() - startTime;
+        if (options.onProgress) {
+            options.onProgress(`Batch create complete: ${createdCount} created, ${errors.length} errors`);
+        }
+        return {
+            success: errors.length === 0,
+            createdCount,
+            sysIds,
+            errors,
+            executionTimeMs
+        };
+    }
+    /**
+     * Execute a batch of update operations sequentially.
+     *
+     * @param options Batch update options including updates list and stopOnError flag
+     * @returns BatchUpdateResult with counts, errors, and timing
+     */
+    async batchUpdate(options) {
+        const startTime = Date.now();
+        const stopOnError = options.stopOnError ?? false;
+        const errors = [];
+        let updatedCount = 0;
+        this._logger.info(`Starting batch update with ${options.updates.length} updates (stopOnError=${stopOnError})`);
+        for (let i = 0; i < options.updates.length; i++) {
+            const update = options.updates[i];
+            try {
+                if (options.onProgress) {
+                    options.onProgress(`Updating record ${i + 1}/${options.updates.length} in table '${update.table}'`);
+                }
+                this._logger.info(`Batch update [${i + 1}/${options.updates.length}]: PUT to '${update.table}/${update.sysId}'`);
+                const response = await this._tableAPI.put(update.table, update.sysId, update.data);
+                if (response && response.status === 200 && response.bodyObject?.result) {
+                    updatedCount++;
+                    this._logger.info(`Batch update [${i + 1}]: Updated '${update.table}/${update.sysId}'`);
+                }
+                else {
+                    const errorMsg = `Failed to update record '${update.sysId}' in '${update.table}'. Status: ${response?.status ?? 'unknown'}`;
+                    this._logger.error(errorMsg);
+                    errors.push({ updateIndex: i, table: update.table, sysId: update.sysId, error: errorMsg });
+                    if (stopOnError) {
+                        if (options.onProgress) {
+                            options.onProgress(`Stopping batch: error at update ${i + 1}`);
+                        }
+                        break;
+                    }
+                }
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                this._logger.error(`Batch update [${i + 1}] exception: ${errorMsg}`);
+                errors.push({ updateIndex: i, table: update.table, sysId: update.sysId, error: errorMsg });
+                if (stopOnError) {
+                    if (options.onProgress) {
+                        options.onProgress(`Stopping batch: error at update ${i + 1}`);
+                    }
+                    break;
+                }
+            }
+        }
+        const executionTimeMs = Date.now() - startTime;
+        if (options.onProgress) {
+            options.onProgress(`Batch update complete: ${updatedCount} updated, ${errors.length} errors`);
+        }
+        return {
+            success: errors.length === 0,
+            updatedCount,
+            errors,
+            executionTimeMs
+        };
+    }
+    /**
+     * Resolve ${variable} references in data values using the sysIds map.
+     * Serializes the data to JSON, replaces all ${key} patterns with the
+     * corresponding sys_id value, then deserializes back.
+     *
+     * @param data The record data that may contain variable references
+     * @param sysIds Map of variable names to sys_id values
+     * @returns A new data object with all references resolved
+     */
+    resolveVariableReferences(data, sysIds) {
+        if (Object.keys(sysIds).length === 0) {
+            return data;
+        }
+        let json = JSON.stringify(data);
+        for (const [key, value] of Object.entries(sysIds)) {
+            // Use a global regex to replace all occurrences of ${key}
+            const pattern = new RegExp('\\$\\{' + key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\}', 'g');
+            json = json.replace(pattern, value);
+        }
+        return JSON.parse(json);
+    }
+}
+//# sourceMappingURL=BatchOperations.js.map

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

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

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

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

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

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

@@ -0,0 +1,41 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { QueryUpdateOptions, QueryDeleteOptions, QueryUpdateResult, QueryDeleteResult } from './QueryBatchModels.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 declare class QueryBatchOperations {
+    private static readonly DEFAULT_LIMIT;
+    private static readonly MAX_LIMIT;
+    private _logger;
+    private _req;
+    private _tableAPI;
+    private _instance;
+    private _headers;
+    constructor(instance: ServiceNowInstance);
+    /**
+     * 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
+     */
+    queryUpdate(options: QueryUpdateOptions): Promise<QueryUpdateResult>;
+    /**
+     * 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
+     */
+    queryDelete(options: QueryDeleteOptions): Promise<QueryDeleteResult>;
+    /**
+     * Find records matching a query and return their sys_ids.
+     * Only fetches sys_id field for efficiency.
+     * @private
+     */
+    private _findMatchingRecords;
+}