@jacebenson/jsn 4.3.13 → 4.4.0-dev.113.1

package/src/sdk.js

@@ -1,7 +1,8 @@
 // ServiceNow REST API client
 
+import { batchRead } from './sdk-batch.js';
 import { gunzipSync } from 'node:zlib';
-import { errAuth, errAPI, errNetwork } from './errors.js';
+import { AppError, CodeAPI, CodeAuth, errAuth, errAPI, errNetwork, errUsage } from './errors.js';
 import { getStringField } from './helpers.js';
 import { getAction, getStepTypes, createAction, updateAction, testAction } from './processflow-actions.js';
 import { readSkippedBaseline, revertSkippedUpdate } from './skipped-update-provider.js';
@@ -47,6 +48,8 @@ export class SDKClient {
   constructor(baseURL, authProvider, opts = {}) {
     this.baseURL = baseURL.replace(/\/$/, '');
     this.authProvider = authProvider;
+    this.recovery = opts.recovery;
+    this.onMutation = opts.onMutation;
     this.timeout = opts.timeout || DEFAULT_TIMEOUT;
     this.domain = opts.domain || '';
     this.oauthCookies = null;
@@ -58,7 +61,13 @@ export class SDKClient {
     if (!this.authProvider) {
       throw errAuth('No authentication configured');
     }
-    const creds = await this.authProvider.getCredentials();
+    let creds;
+    try {
+      creds = await this.authProvider.getCredentials();
+    } catch (error) {
+      if (error.code === CodeAuth && this.recovery?.credentialError) throw this.recovery.credentialError(error);
+      throw error;
+    }
     if (!creds) {
       throw errAuth('No valid credentials');
     }
@@ -97,26 +106,85 @@ export class SDKClient {
 
   // Keep the timeout alive through body consumption for text/JSON requests.
   // Raw-response callers retain their existing timeout boundary at headers.
-  async _withAuthenticatedRequest(endpoint, opts, {
+  async _withAuthenticatedRequest(endpoint, opts, settings, consume = (response) => response) {
+    const url = new URL(endpoint);
+    const match = url.pathname.match(/^\/api\/now\/table\/([^/]+)(?:\/([^/]+))?\/?$/);
+    const operation = { POST: 'create', PUT: 'update', PATCH: 'update', DELETE: 'delete' }[(opts.method || 'GET').toUpperCase()];
+    const event = match && operation && this.onMutation ? {
+      table: decodeURIComponent(match[1]), sys_id: match[2] ? decodeURIComponent(match[2]) : null, operation,
+    } : null;
+    let result;
+    try {
+      result = await this._performAuthenticatedRequest(endpoint, opts, settings, async response => {
+        if (event) event.http_status = response.status;
+        const value = await consume(response);
+        if (event && value instanceof Response && response.ok && operation === 'create') {
+          try { event.sys_id = (await response.clone().json())?.result?.sys_id || null; } catch { /* ID remains unknown. */ }
+        }
+        return value;
+      });
+    } catch (error) {
+      if (event) await this._reportMutation({ ...event, outcome: error.status >= 400 && error.status < 500 && error.status !== 408
+        ? 'failed' : 'unknown', http_status: error.status || null });
+      throw error;
+    }
+    if (event) {
+      let body = result;
+      if (typeof body === 'string') { try { body = JSON.parse(body); } catch { body = null; } }
+      const id = body?.result?.sys_id;
+      if (typeof id === 'string') event.sys_id = id;
+      else if (typeof id?.value === 'string') event.sys_id = id.value;
+      await this._reportMutation({ ...event, outcome: event.http_status >= 400
+        ? (event.http_status < 500 && event.http_status !== 408 ? 'failed' : 'unknown')
+        : (event.sys_id ? 'succeeded' : 'unknown') });
+    }
+    return result;
+  }
+
+  async _reportMutation(event) {
+    // History failures must never change the outcome of a completed remote write.
+    try { await this.onMutation(event); } catch { /* App callback reports local storage failures. */ }
+  }
+
+  async _performAuthenticatedRequest(endpoint, opts, {
     timeout = this.timeout, prepare, skipOAuthSession = false, normalizeErrors = false,
   }, consume = (response) => response) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-      const req = new Request(endpoint, { ...opts, signal: controller.signal });
-      if (prepare) prepare(req);
-      await this._setAuth(req, { skipOAuthSession });
-      return await consume(await fetch(req));
-    } catch (err) {
-      if (normalizeErrors) {
-        if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
-        if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
-          throw errNetwork(err);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      let rejection;
+      try {
+        const req = new Request(endpoint, { ...opts, signal: controller.signal });
+        if (prepare) prepare(req);
+        await this._setAuth(req, { skipOAuthSession });
+        const response = await fetch(req);
+        if (!skipOAuthSession && response.status === 401 && this.recovery) {
+          // Only a definitive HTTP rejection permits replay, including POST.
+          // Do not consume/echo the provider's potentially sensitive body.
+          rejection = { status: response.status, method: req.method, url: req.url };
+          await response.body?.cancel();
+        } else {
+          return await consume(response);
+        }
+      } catch (err) {
+        if (normalizeErrors) {
+          if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
+          if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+            throw errNetwork(err);
+          }
         }
+        throw err;
+      } finally {
+        clearTimeout(timer);
       }
-      throw err;
-    } finally {
-      clearTimeout(timer);
+      // Browser renewal has its own existing hard timeout. Never leave a
+      // request timeout running while waiting for the human to authenticate.
+      if (attempt === 0 && await this.recovery.recover(rejection)) {
+        this.oauthCookies = null;
+        this.sessionUserToken = '';
+        continue;
+      }
+      throw this.recovery.error || errAPI(401, '');
     }
   }
 
@@ -174,6 +242,11 @@ export class SDKClient {
     });
   }
 
+  // Explicit opt-in; ordinary SDK methods remain unbatched.
+  async batch(requests, options = {}) {
+    return batchRead(this, requests, options);
+  }
+
   async getSkippedUpdateBaseline(sysID) {
     return readSkippedBaseline(this, sysID);
   }
@@ -695,6 +768,72 @@ export class SDKClient {
     });
   }
 
+  /** Load through the native XML upload processor, then verify the exact envelope. */
+  async importUpdateSet(xml, inspection, filename = 'update-set.xml') {
+    const { sys_id: id, remote_sys_id: sourceID } = inspection;
+    const params = new URLSearchParams({
+      sysparm_query: `sys_id=${id}^ORremote_sys_id=${sourceID}`,
+      sysparm_fields: 'sys_id,name,state', sysparm_limit: '2', sysparm_display_value: 'false',
+    });
+    if ((await this.list('sys_remote_update_set', params)).length) {
+      throw errUsage('This retrieved update set already exists on the target; refusing to overwrite it. Inspect it before retrying.');
+    }
+    // Native INSERT_OR_UPDATE must not move/overwrite a member belonging to another set.
+    for (let offset = 0; offset < inspection.members.length; offset += 50) {
+      const ids = inspection.members.slice(offset, offset + 50).map(member => member.sys_id).join(',');
+      const existing = await this.list('sys_update_xml', new URLSearchParams({
+        sysparm_query: `sys_idIN${ids}`, sysparm_fields: 'sys_id', sysparm_limit: '1',
+      }));
+      if (existing.length) throw errUsage('An XML member already exists on the target; refusing to overwrite or move existing updates.');
+    }
+    const cookies = await this._warmSession();
+    const formURL = `${this.baseURL}/upload.do?sysparm_target=sys_remote_update_set`;
+    const html = await this.rawRequest(formURL, { method: 'GET', headers: cookies ? { Cookie: cookies } : {} });
+    const csrf = html.match(/name=["']sysparm_ck["'][^>]*value=["']([^"']+)["']/i)?.[1];
+    if (!csrf || !/action=["']\/sys_upload\.do["']/i.test(html) || !/name=["']attachFile["']/i.test(html)) {
+      throw errUsage('The native XML upload form is unavailable; no XML was uploaded. Check admin access and session authentication.');
+    }
+    const form = new FormData();
+    form.set('sysparm_ck', csrf);
+    form.set('sysparm_target', 'sys_remote_update_set');
+    form.set('sysparm_upload_prefix', '');
+    form.set('sysparm_referring_url', 'sys_remote_update_set_list.do');
+    form.set('attachFile', new Blob([xml], { type: 'application/xml' }), filename);
+    let outcome = 'unknown';
+    try {
+      await this.rawRequest(`${this.baseURL}/sys_upload.do`, { method: 'POST', body: form,
+        headers: { ...(cookies ? { Cookie: cookies } : {}), 'X-UserToken': csrf, Referer: formURL },
+      });
+      const records = await this.list('sys_remote_update_set', params);
+      if (records.length !== 1) throw new Error('Could not identify exactly one uploaded retrieved update set');
+      const record = records[0];
+      const importedID = getStringField(record, 'sys_id');
+      const state = getStringField(record, 'state');
+      if (state !== 'loaded' || getStringField(record, 'name') !== inspection.name) throw new Error('Uploaded update set name/state did not match the loaded export');
+      const members = [];
+      for (let offset = 0; ; offset += 500) {
+        const page = await this.list('sys_update_xml', new URLSearchParams({
+          sysparm_query: `remote_update_set=${importedID}^ORDERBYsys_id`, sysparm_limit: '500',
+          sysparm_offset: String(offset), sysparm_display_value: 'false', sysparm_fields: 'sys_id,name,action',
+        }));
+        members.push(...page);
+        if (members.length > inspection.count) throw new Error('Uploaded update set contains unexpected extra members');
+        if (page.length < 500) break;
+      }
+      const actual = new Map(members.map(member => [getStringField(member, 'sys_id'), member]));
+      if (actual.size !== inspection.count || inspection.members.some(expected => {
+        const member = actual.get(expected.sys_id);
+        return !member || getStringField(member, 'name') !== expected.name || getStringField(member, 'action') !== expected.action;
+      })) throw new Error('Uploaded update set members did not match the XML export');
+      outcome = 'succeeded';
+      return { sys_id: importedID, state, count: members.length, link: `${this.baseURL}/sys_remote_update_set.do?sys_id=${importedID}` };
+    } catch (error) {
+      throw new AppError(CodeAPI, `XML import could not be verified: ${error.message}. It may have partially loaded; inspect Retrieved Update Sets before retrying. No automatic retry was attempted.`, 'Inspect Retrieved Update Sets before retrying.', 0, error);
+    } finally {
+      if (this.onMutation) await this._reportMutation({ table: 'sys_remote_update_set', sys_id: id, operation: 'create', outcome });
+    }
+  }
+
   /**
    * Execute a background script on the ServiceNow instance via sys.scripts.do.
    * Uses a 3-step session-establishment flow compatible with OAuth tokens:

package/src/update-set-xml.js

@@ -0,0 +1,89 @@
+// Parse the export envelope without evaluating its payload or resolving entities.
+import { SaxesParser } from 'saxes';
+import { errUsage } from './errors.js';
+
+export const MAX_UPDATE_SET_BYTES = 50 * 1024 * 1024;
+const ID = /^[a-f0-9]{32}$/i;
+
+export function updateSetFilename(name) {
+  const stem = String(name).normalize('NFKC').replace(/[^a-z0-9._-]+/gi, '-').replace(/^[.-]+|[.-]+$/g, '').slice(0, 180);
+  return `${stem || 'update-set'}.xml`;
+}
+
+export function inspectUpdateSetXML(xml) {
+  if (Buffer.byteLength(xml, 'utf8') > MAX_UPDATE_SET_BYTES) throw errUsage('Update set XML exceeds the 50 MiB limit');
+  const parser = new SaxesParser();
+  const stack = [], sets = [], updates = [];
+  let record;
+  parser.on('doctype', () => { throw errUsage('DOCTYPE and external entities are not allowed in update set XML'); });
+  parser.on('opentag', tag => {
+    stack.push(tag.name);
+    if (stack.length === 1 && tag.name !== 'unload') throw errUsage('Expected an update set export with an <unload> root');
+    if (stack.length === 2) {
+      if (!['sys_remote_update_set', 'sys_update_xml'].includes(tag.name) || tag.attributes.action !== 'INSERT_OR_UPDATE') {
+        throw errUsage('Only INSERT_OR_UPDATE sys_remote_update_set and sys_update_xml envelope records may be imported');
+      }
+      record = {};
+    }
+    if (stack.length === 3) {
+      if (Object.hasOwn(record, tag.name)) throw errUsage(`Duplicate XML field: ${tag.name}`);
+      record[tag.name] = '';
+    }
+    if (stack.length > 3) throw errUsage('Update payloads must be XML text or CDATA, not nested envelope elements');
+  });
+  const text = value => { if (stack.length === 3) record[stack[2]] += value; };
+  parser.on('text', text); parser.on('cdata', text);
+  parser.on('closetag', () => {
+    if (stack.length === 2) (stack[1] === 'sys_remote_update_set' ? sets : updates).push(record);
+    stack.pop();
+  });
+  try { parser.write(xml).close(); } catch (error) { throw errUsage(`Invalid update set XML: ${error.message}`); }
+  if (sets.length !== 1) throw errUsage('Import exactly one retrieved update set per XML file');
+  const set = sets[0];
+  if (!ID.test(set.sys_id || '') || !ID.test(set.remote_sys_id || '') || !set.name?.trim()) {
+    throw errUsage('Update set requires a name, sys_id, and remote_sys_id');
+  }
+  if (set.sys_class_name && set.sys_class_name !== 'sys_remote_update_set') throw errUsage('Invalid retrieved update set class');
+  if (set.state !== 'loaded' || set.update_set?.trim()) throw errUsage('Expected a loaded, uncommitted retrieved update set export');
+  const seen = new Set();
+  const summary = new Map(), payloadOperations = new Map();
+  for (const update of updates) {
+    if (!ID.test(update.sys_id || '') || seen.has(update.sys_id.toLowerCase()) || update.remote_update_set !== set.sys_id
+      || update.update_set?.trim() || !update.name || !update.payload?.trim()
+      || !['INSERT_OR_UPDATE', 'DELETE'].includes(update.action)) {
+      throw errUsage('Invalid, duplicate, or unrelated update XML member');
+    }
+    if (update.sys_class_name && update.sys_class_name !== 'sys_update_xml') throw errUsage('Invalid update XML class');
+    seen.add(update.sys_id.toLowerCase());
+    // Payload XML stays inert; parse it solely to describe the affected table.
+    const payload = new SaxesParser(); let table = '', depth = 0, primary = '';
+    payload.on('doctype', () => { throw errUsage('DOCTYPE is not allowed in update payloads'); });
+    payload.on('opentag', tag => {
+      depth++;
+      if (depth === 1 && tag.name !== 'record_update') throw errUsage('Expected a record_update payload');
+      if (depth === 1) table = tag.attributes.table || '';
+      if (depth === 2) {
+        if (!primary) {
+          primary = tag.name;
+          if (table && table !== primary) throw errUsage('Payload table does not match its primary record');
+          table = primary;
+          if (tag.attributes.action && tag.attributes.action !== update.action) throw errUsage('Payload action does not match the update member action');
+        }
+        const action = tag.attributes.action || 'platform_default';
+        if (!['INSERT_OR_UPDATE', 'INSERT', 'UPDATE', 'DELETE', 'delete_multiple', 'platform_default'].includes(action)) throw errUsage('Unsupported payload record action');
+        const key = `${tag.name}:${action}`;
+        const operation = payloadOperations.get(key) || { table: tag.name, action, count: 0 };
+        operation.count++; payloadOperations.set(key, operation);
+      }
+    });
+    payload.on('closetag', () => { depth--; });
+    try { payload.write(update.payload).close(); } catch (error) { throw errUsage(`Invalid update payload: ${error.message}`); }
+    if (!primary || !/^[a-z][a-z0-9_]*$/i.test(table)) throw errUsage(`Missing or invalid payload table for ${update.name}`);
+    const key = `${table}:${update.action}`;
+    const row = summary.get(key) || { table, action: update.action, count: 0 };
+    row.count++; summary.set(key, row);
+  }
+  return { name: set.name, sys_id: set.sys_id, remote_sys_id: set.remote_sys_id,
+    state: set.state, count: updates.length, summary: [...summary.values()], payload_operations: [...payloadOperations.values()],
+    members: updates.map(update => ({ sys_id: update.sys_id, name: update.name, target_name: update.target_name || '', action: update.action })) };
+}