@sonisoft/now-sdk-ext-core 3.0.1 → 3.3.0

package/dist/sn/xml/XMLRecordManager.js

@@ -0,0 +1,157 @@
+import { Parser } from 'xml2js';
+import { ServiceNowRequest } from '../../comm/http/ServiceNowRequest.js';
+import { Logger } from '../../util/Logger.js';
+import { CSRFTokenHelper } from '../../util/CSRFTokenHelper.js';
+const UPLOAD_ENDPOINT = '/upload.do';
+const SYS_UPLOAD_ENDPOINT = '/sys_upload.do';
+/**
+ * Manages XML record export (unload) and import (upload) operations
+ * against ServiceNow `.do` processor endpoints.
+ */
+export class XMLRecordManager {
+    _snRequest;
+    _logger = new Logger('XMLRecordManager');
+    constructor(instance) {
+        this._snRequest = new ServiceNowRequest(instance);
+    }
+    /**
+     * Export a single record as XML (ServiceNow unload format).
+     *
+     * @param options - Table name and sys_id of the record to export
+     * @returns The raw XML string plus parsed metadata (table, sysId, unloadDate)
+     */
+    async exportRecord(options) {
+        if (!options.table || !options.table.trim()) {
+            throw new Error('table is required for exportRecord');
+        }
+        if (!options.sysId || !options.sysId.trim()) {
+            throw new Error('sysId is required for exportRecord');
+        }
+        const path = `/${options.table}.do`;
+        const request = {
+            path,
+            headers: null,
+            query: {
+                UNL: '',
+                sysparm_query: `sys_id=${options.sysId}`
+            },
+            body: null
+        };
+        this._logger.debug(`Exporting record: ${options.table}/${options.sysId}`);
+        const response = await this._snRequest.get(request);
+        if (response.status !== 200 || !response.data) {
+            throw new Error(`Failed to export record ${options.table}/${options.sysId}. ` +
+                `Status: ${response.status}`);
+        }
+        const xml = response.data;
+        const metadata = await this._parseUnloadXml(xml);
+        return {
+            xml,
+            table: metadata.table || options.table,
+            sysId: metadata.sysId || options.sysId,
+            unloadDate: metadata.unloadDate
+        };
+    }
+    /**
+     * Import XML records into ServiceNow via the sys_upload.do processor.
+     *
+     * Acquires a CSRF token first, then POSTs a multipart form with the XML content.
+     *
+     * @param options - XML content and target table name
+     * @returns Success status and the target table
+     */
+    async importRecords(options) {
+        if (!options.xmlContent || !options.xmlContent.trim()) {
+            throw new Error('xmlContent is required for importRecords');
+        }
+        if (!options.targetTable || !options.targetTable.trim()) {
+            throw new Error('targetTable is required for importRecords');
+        }
+        // Step 1: Get CSRF token
+        const csrfToken = await this._getUploadCSRFToken();
+        if (!csrfToken) {
+            throw new Error('Failed to obtain CSRF token from /upload.do. ' +
+                'This may indicate an authentication failure or insufficient permissions.');
+        }
+        // Step 2: Build multipart form
+        const formData = new FormData();
+        formData.append('sysparm_ck', csrfToken);
+        formData.append('sysparm_upload_prefix', '');
+        formData.append('sysparm_referring_url', '');
+        formData.append('sysparm_target', options.targetTable);
+        const blob = new Blob([options.xmlContent], { type: 'text/xml' });
+        formData.append('attachFile', blob, 'upload.xml');
+        // Step 3: POST to sys_upload.do
+        // Do NOT set Content-Type header — let fetch auto-set it with the multipart boundary
+        const request = {
+            path: SYS_UPLOAD_ENDPOINT,
+            headers: {},
+            query: null,
+            body: formData
+        };
+        this._logger.debug(`Importing records to table: ${options.targetTable}`);
+        const response = await this._snRequest.post(request);
+        if (response.status !== 200) {
+            throw new Error(`Failed to import records to ${options.targetTable}. ` +
+                `Status: ${response.status}`);
+        }
+        return {
+            success: true,
+            targetTable: options.targetTable,
+            responseBody: response.data || undefined
+        };
+    }
+    /**
+     * Fetch the CSRF token from /upload.do by parsing the sysparm_ck hidden input.
+     */
+    async _getUploadCSRFToken() {
+        const request = {
+            path: UPLOAD_ENDPOINT,
+            headers: null,
+            query: null,
+            body: null
+        };
+        const response = await this._snRequest.get(request);
+        if (response.status === 200 && response.data) {
+            const token = CSRFTokenHelper.extractCSRFToken(response.data);
+            this._logger.debug('CSRF Token Received', { token });
+            return token;
+        }
+        this._logger.error('Failed to fetch CSRF token from /upload.do', { status: response.status });
+        return null;
+    }
+    /**
+     * Parse ServiceNow unload XML to extract metadata (table name, sys_id, unload_date).
+     */
+    async _parseUnloadXml(xml) {
+        try {
+            const parser = new Parser({ explicitArray: false });
+            const result = await new Promise((resolve, reject) => {
+                parser.parseString(xml, (err, parsed) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve(parsed);
+                });
+            });
+            if (!result?.unload) {
+                return {};
+            }
+            const unloadDate = result.unload.$?.unload_date;
+            // Find the first child element that is the record (not $ which holds attributes)
+            const recordKeys = Object.keys(result.unload).filter(k => k !== '$');
+            if (recordKeys.length === 0) {
+                return { unloadDate };
+            }
+            const tableName = recordKeys[0];
+            const record = result.unload[tableName];
+            const sysId = record?.sys_id;
+            return { table: tableName, sysId, unloadDate };
+        }
+        catch (err) {
+            this._logger.warn('Failed to parse unload XML for metadata', { error: err });
+            return {};
+        }
+    }
+}
+//# sourceMappingURL=XMLRecordManager.js.map

package/dist/sn/xml/XMLRecordManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XMLRecordManager.js","sourceRoot":"","sources":["../../../src/sn/xml/XMLRecordManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAGtE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAQ7D,MAAM,eAAe,GAAG,YAAY,CAAC;AACrC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAE7C;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACjB,UAAU,CAAoB;IAC9B,OAAO,GAAW,IAAI,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAEzD,YAAmB,QAA4B;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,YAAY,CAAC,OAA4B;QAClD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC;QACpC,MAAM,OAAO,GAAgB;YACzB,IAAI;YACJ,OAAO,EAAE,IAAI;YACb,KAAK,EAAE;gBACH,GAAG,EAAE,EAAE;gBACP,aAAa,EAAE,UAAU,OAAO,CAAC,KAAK,EAAE;aAC3C;YACD,IAAI,EAAE,IAAI;SACb,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,qBAAqB,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAA0B,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAS,OAAO,CAAC,CAAC;QAEnF,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACX,2BAA2B,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI;gBAC7D,WAAW,QAAQ,CAAC,MAAM,EAAE,CAC/B,CAAC;QACN,CAAC;QAED,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAEjD,OAAO;YACH,GAAG;YACH,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK;YACtC,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK;YACtC,UAAU,EAAE,QAAQ,CAAC,UAAU;SAClC,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,aAAa,CAAC,OAA6B;QACpD,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QAED,yBAAyB;QACzB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACX,+CAA+C;gBAC/C,0EAA0E,CAC7E,CAAC;QACN,CAAC;QAED,+BAA+B;QAC/B,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;QAChC,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACzC,QAAQ,CAAC,MAAM,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;QAC7C,QAAQ,CAAC,MAAM,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;QAC7C,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QAEvD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QAClE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;QAElD,gCAAgC;QAChC,qFAAqF;QACrF,MAAM,OAAO,GAAgB;YACzB,IAAI,EAAE,mBAAmB;YACzB,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,QAAQ;SACjB,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,+BAA+B,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACzE,MAAM,QAAQ,GAA0B,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAS,OAAO,CAAC,CAAC;QAEpF,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACX,+BAA+B,OAAO,CAAC,WAAW,IAAI;gBACtD,WAAW,QAAQ,CAAC,MAAM,EAAE,CAC/B,CAAC;QACN,CAAC;QAED,OAAO;YACH,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,QAAQ,CAAC,IAAI,IAAI,SAAS;SAC3C,CAAC;IACN,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,mBAAmB;QAC7B,MAAM,OAAO,GAAgB;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,IAAI;SACb,CAAC;QAEF,MAAM,QAAQ,GAA0B,MAAM,IAAI,CAAC,UAAU,CAAC,GAAG,CAAS,OAAO,CAAC,CAAC;QAEnF,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,eAAe,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACrD,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9F,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAAC,GAAW;QACrC,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;YACpD,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACtD,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,GAAiB,EAAE,MAAW,EAAE,EAAE;oBACvD,IAAI,GAAG;wBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;wBAChB,OAAO,CAAC,MAAM,CAAC,CAAC;gBACzB,CAAC,CAAC,CAAC;YACP,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAClB,OAAO,EAAE,CAAC;YACd,CAAC;YAED,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC;YAEhD,iFAAiF;YACjF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;YACrE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;YAC1B,CAAC;YAED,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAChC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACxC,MAAM,KAAK,GAAG,MAAM,EAAE,MAAM,CAAC;YAE7B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yCAAyC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YAC7E,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;CACJ"}

package/dist/sn/xml/XMLRecordModels.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Options for exporting a single ServiceNow record as XML (unload).
+ */
+export interface ExportRecordOptions {
+    /** The table name (e.g. 'incident', 'kb_knowledge') */
+    table: string;
+    /** The sys_id of the record to export */
+    sysId: string;
+}
+/**
+ * Result of an XML record export operation.
+ */
+export interface ExportRecordResult {
+    /** The raw XML string returned by the platform */
+    xml: string;
+    /** The table name extracted from the XML envelope */
+    table: string;
+    /** The sys_id extracted from the XML record */
+    sysId: string;
+    /** The unload_date attribute from the XML envelope, if present */
+    unloadDate?: string;
+}
+/**
+ * Options for importing XML records into ServiceNow.
+ */
+export interface ImportRecordsOptions {
+    /** The raw XML content to upload (ServiceNow unload format) */
+    xmlContent: string;
+    /** The target table name (e.g. 'kb_knowledge') */
+    targetTable: string;
+}
+/**
+ * Result of an XML record import operation.
+ */
+export interface ImportRecordsResult {
+    /** Whether the upload request completed successfully (HTTP 200) */
+    success: boolean;
+    /** The target table the XML was uploaded to */
+    targetTable: string;
+    /** The raw response body from the upload confirmation page, if available */
+    responseBody?: string;
+}

package/dist/sn/xml/XMLRecordModels.js

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

package/dist/sn/xml/XMLRecordModels.js.map

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

package/dist/util/CSRFTokenHelper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared utility for extracting CSRF tokens (sysparm_ck) from ServiceNow HTML pages.
+ *
+ * ServiceNow embeds CSRF tokens as hidden input fields in `.do` processor pages.
+ * The HTML attribute order can vary between pages and platform versions, so a regex
+ * approach is more robust than fixed-string substring matching.
+ */
+export declare class CSRFTokenHelper {
+    /**
+     * Extracts the `sysparm_ck` CSRF token value from an HTML string.
+     *
+     * @param html - Raw HTML response from a ServiceNow `.do` page
+     * @returns The token string, or `null` if not found
+     */
+    static extractCSRFToken(html: string): string | null;
+}

package/dist/util/CSRFTokenHelper.js

@@ -0,0 +1,23 @@
+/**
+ * Shared utility for extracting CSRF tokens (sysparm_ck) from ServiceNow HTML pages.
+ *
+ * ServiceNow embeds CSRF tokens as hidden input fields in `.do` processor pages.
+ * The HTML attribute order can vary between pages and platform versions, so a regex
+ * approach is more robust than fixed-string substring matching.
+ */
+export class CSRFTokenHelper {
+    /**
+     * Extracts the `sysparm_ck` CSRF token value from an HTML string.
+     *
+     * @param html - Raw HTML response from a ServiceNow `.do` page
+     * @returns The token string, or `null` if not found
+     */
+    static extractCSRFToken(html) {
+        if (!html) {
+            return null;
+        }
+        const match = html.match(/name="sysparm_ck"[^>]*value="([^"]+)"/);
+        return match ? match[1] : null;
+    }
+}
+//# sourceMappingURL=CSRFTokenHelper.js.map

package/dist/util/CSRFTokenHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CSRFTokenHelper.js","sourceRoot":"","sources":["../../src/util/CSRFTokenHelper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAExB;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAY;QAChC,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAClE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnC,CAAC;CACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonisoft/now-sdk-ext-core",
-  "version": "3.0.1",
+  "version": "3.3.0",
   "description": "Comprehensive TypeScript library extending ServiceNow SDK with application management, ATF testing, real-time log monitoring, AMB event subscriptions, and automation tools",
   "keywords": [
     "servicenow",