@jacebenson/jsn 4.3.13-dev.79.1 → 4.3.13-dev.81.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.79.1",
+  "version": "4.3.13-dev.81.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/app.js

@@ -7,6 +7,7 @@
 // setEffectiveInstance() are thin session-backed shims kept for the many
 // command handlers that already call them.
 
+import { appendMutation } from './mutation-history.js';
 import { AuthManager } from './auth.js';
 import { createAuthRecovery } from './auth-recovery.js';
 import { SDKClient } from './sdk.js';
@@ -59,6 +60,7 @@ export class App {
     }), {
       domain: session?.domain || '',
       recovery: createAuthRecovery({ app: this, session }),
+      onMutation: event => this.recordMutation(instance, session?.profileName, event),
     });
   }
 
@@ -67,9 +69,21 @@ export class App {
     const profile = options.profile || {};
     return new SDKClient(instance, this.auth.createProfileProvider(instance, options), {
       domain: options.domain ?? profile.domain ?? '',
+      onMutation: event => this.recordMutation(instance, options.profileName || null, event),
     });
   }
 
+  recordMutation(instance, profile, event) {
+    if (!this._authArgv) return;
+    try { appendMutation({ ...event, instance, profile, reason: this._authArgv.reason }); }
+    catch {
+      if (!this._historyWarningShown) {
+        process.stderr.write('Warning: local mutation history could not be saved. The remote result is unchanged.\n');
+        this._historyWarningShown = true;
+      }
+    }
+  }
+
   loadContext() {
     this.context = contextFromSession(this.session, this.config);
   }

package/src/cli.js

@@ -71,6 +71,7 @@ import { scrapiCmd } from './commands/scrapi.js';
 import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
+import { historyCmd } from './commands/history.js';
 import { perfCmd } from './commands/perf.js';
 import { customizationsCmd } from './commands/customizations.js';
 import { midserversCmd } from './commands/midservers.js';
@@ -146,6 +147,8 @@ export function buildCLI() {
       },
     ])
     .options({
+      reason: { type: 'string', describe: 'Optional non-sensitive reason saved in local mutation history' },
+
       force: {
         type: 'boolean',
         description: 'Approve Global + Default mutation context only after user approval; delete commands also use this for their separate confirmation',
@@ -416,6 +419,7 @@ export function buildCLI() {
     .command(approvalsCmd(wrap))
     .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))
+    .command(historyCmd(wrap))
     .command(customizationsCmd(wrap))
     .command(midserversCmd(wrap))
     .command(diffCmd(wrap))

package/src/commands/history.js

@@ -0,0 +1,26 @@
+import { declareCapabilities } from '../capabilities.js';
+import { listHistory, pruneHistory } from '../mutation-history.js';
+
+export function historyCmd(wrap) {
+  declareCapabilities('history', { noInstance: true, skipDailyChecks: true });
+  const list = wrap(async (argv, app) => {
+    const entries = listHistory({ ...argv, instance: argv['instance-url'], profile: argv['profile-name'] });
+    app.ok({ entries, retentionDays: 7, _formatted: entries.length
+      ? entries.map(e => `${e.timestamp} ${e.operation} ${e.table}/${e.sys_id || '(unknown ID)'} ${e.outcome} ${e.instance}${e.reason ? ` — ${e.reason}` : ''}`).join('\n')
+      : 'No local mutations in the last seven days.' });
+  });
+  const filters = b => b
+    .option('since', { type: 'string', describe: 'Earliest ISO timestamp' })
+    .option('until', { type: 'string', describe: 'Latest ISO timestamp' })
+    .option('instance-url', { type: 'string', describe: 'Filter by instance origin' })
+    .option('profile-name', { type: 'string', describe: 'Filter by recorded profile name (including removed profiles)' })
+    .option('table', { type: 'string', describe: 'Filter by table' })
+    .option('operation', { choices: ['create', 'update', 'delete'], type: 'string' })
+    .option('record', { type: 'string', describe: 'Filter by full resolved sys_id' })
+    .option('limit', { type: 'number', default: 50, describe: 'Maximum entries (1–10000)' });
+  return { command: 'history [subcommand]', describe: 'Local seven-day mutation history (not a durable ServiceNow audit)',
+    builder: y => filters(y).command({ command: 'list', describe: 'List local mutations', builder: filters, handler: list })
+      .command({ command: 'prune', describe: 'Remove expired entries only', handler: wrap(async (_argv, app) => {
+        app.ok({ ...pruneHistory(), _formatted: 'Expired local history removed; seven days retained.' });
+      }) }), handler: list };
+}

package/src/mutation-history.js

@@ -0,0 +1,75 @@
+// Local convenience history, independent of documentation indexes and sync.
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { errUsage } from './errors.js';
+
+export const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const operations = ['create', 'update', 'delete'];
+const outcomes = ['succeeded', 'failed', 'unknown'];
+export function historyPath() {
+  return path.join(process.env.JSN_DATA_HOME || path.join(os.homedir(), '.jsn'), 'history.db');
+}
+function openHistory(filename, now) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const db = new Database(filename);
+  try {
+    if (process.platform !== 'win32') fs.chmodSync(filename, 0o600);
+    db.pragma('busy_timeout = 3000');
+    db.exec(`CREATE TABLE IF NOT EXISTS mutation_history (
+      id INTEGER PRIMARY KEY, timestamp INTEGER NOT NULL, instance TEXT NOT NULL,
+      profile TEXT, table_name TEXT NOT NULL, sys_id TEXT, operation TEXT NOT NULL,
+      outcome TEXT NOT NULL, reason TEXT, http_status INTEGER
+    ); CREATE INDEX IF NOT EXISTS mutation_history_time ON mutation_history(timestamp)`);
+    db.prepare('DELETE FROM mutation_history WHERE timestamp < ?').run(now - RETENTION_MS);
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+export function sanitizeReason(value) {
+  if (!value) return null;
+  // eslint-disable-next-line no-control-regex -- strip controls from user-supplied prose
+  return String(value).replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\b(?:Bearer|Basic)\s+\S+/gi, '[redacted]')
+    .replace(/\b(password|token|cookie|secret|authorization|access_token|sysparm_ck)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi, '$1=[redacted]')
+    .slice(0, 1000);
+}
+export function appendMutation(event, { filename = historyPath(), now = Date.now() } = {}) {
+  if (!operations.includes(event.operation) || !outcomes.includes(event.outcome)) throw errUsage('Invalid history event');
+  const instance = new URL(event.instance).origin;
+  // Deliberate whitelist: never serialize SDK options, response bodies, or payloads.
+  const row = { timestamp: now, instance, profile: event.profile || null,
+    table_name: event.table, sys_id: event.sys_id || null, operation: event.operation,
+    outcome: event.outcome, reason: sanitizeReason(event.reason), http_status: event.http_status || null };
+  const db = openHistory(filename, now);
+  try {
+    db.prepare(`INSERT INTO mutation_history
+      (timestamp,instance,profile,table_name,sys_id,operation,outcome,reason,http_status)
+      VALUES (@timestamp,@instance,@profile,@table_name,@sys_id,@operation,@outcome,@reason,@http_status)`).run(row);
+  } finally { db.close(); }
+}
+export function pruneHistory({ filename = historyPath(), now = Date.now() } = {}) {
+  const db = openHistory(filename, now);
+  try { return { retentionDays: 7 }; } finally { db.close(); }
+}
+export function listHistory(filters = {}, { filename = historyPath(), now = Date.now() } = {}) {
+  const where = [], values = [];
+  for (const [key, column] of Object.entries({ instance: 'instance', profile: 'profile', table: 'table_name', operation: 'operation', record: 'sys_id' })) {
+    if (filters[key]) { where.push(`${column} = ?`); values.push(key === 'instance' ? new URL(filters[key]).origin : filters[key]); }
+  }
+  for (const [key, operator] of [['since', '>='], ['until', '<=']]) {
+    if (filters[key]) {
+      const time = Date.parse(filters[key]);
+      if (!Number.isFinite(time)) throw errUsage(`Invalid --${key} timestamp; use an ISO date`);
+      where.push(`timestamp ${operator} ?`); values.push(time);
+    }
+  }
+  const limit = filters.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000) throw errUsage('--limit must be an integer from 1 to 10000');
+  const db = openHistory(filename, now);
+  try {
+    return db.prepare(`SELECT id,timestamp,instance,profile,table_name AS "table",sys_id,operation,outcome,reason,http_status
+      FROM mutation_history ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY timestamp DESC,id DESC LIMIT ?`)
+      .all(...values, limit).map(row => ({ ...row, timestamp: new Date(row.timestamp).toISOString() }));
+  } finally { db.close(); }
+}

package/src/sdk-batch.js

@@ -0,0 +1,130 @@
+// Optional, read-only ServiceNow Batch REST transport. No ordinary SDK call is
+// routed here implicitly; writes are deliberately outside this initial contract.
+import { randomUUID } from 'node:crypto';
+import { AppError, errAPI, errUsage } from './errors.js';
+
+const UNSUPPORTED = new Set([404, 405, 501]);
+function malformed(message) { return new AppError('malformed_response', `Invalid Batch API response: ${message}`); }
+function errorData(error) {
+  return { code: error.code || 'network_error', message: error.message, ...(error.status ? { status: error.status } : {}) };
+}
+function normalizeRequests(sdk, requests) {
+  if (!Array.isArray(requests)) throw errUsage('Batch requests must be an array.');
+  const ids = new Set();
+  return requests.map((item, index) => {
+    if (!item || typeof item !== 'object') throw errUsage('Each batch request must be an object.');
+    const id = item.id == null ? String(index + 1) : String(item.id);
+    if (!id || ids.has(id)) throw errUsage('Batch request IDs must be nonempty and unique.');
+    ids.add(id);
+    if (String(item.method || 'GET').toUpperCase() !== 'GET' || item.body !== undefined) {
+      throw errUsage('SDK batch supports GET reads only; send writes through ordinary SDK methods with their existing safety and history contracts.');
+    }
+    if (typeof item.url !== 'string' || !item.url.trim()) throw errUsage('Each batch request needs a same-instance API URL.');
+    let url;
+    try { url = new URL(item.url, `${sdk.baseURL}/`); } catch { throw errUsage('Invalid batch API URL.'); }
+    if (url.origin !== new URL(sdk.baseURL).origin || url.username || url.password || url.hash
+      || !url.pathname.startsWith('/api/') || /\/batch\/?$/.test(url.pathname)) {
+      throw errUsage('Batch URLs must target a same-instance API endpoint; nested batches, credentials, and fragments are unsupported.');
+    }
+    const headers = new Headers(item.headers || {});
+    for (const name of headers.keys()) {
+      if (/^(authorization|cookie|x-usertoken|host|proxy-authorization)$/i.test(name)) throw errUsage('Batch subrequests cannot override authentication headers.');
+    }
+    if (!headers.has('Accept')) headers.set('Accept', 'application/json');
+    if (sdk.domain) headers.set('X-Now-Domain', sdk.domain);
+    return { id, method: 'GET', url: url.pathname + url.search, headers: [...headers].map(([name, value]) => ({ name, value })), exclude_response_headers: true };
+  });
+}
+function decodeBody(body) {
+  if (body == null || body === '') return null;
+  if (typeof body !== 'string') throw malformed('item body must be base64 text');
+  const encoded = body.replace(/\s/g, '');
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw malformed('item body is not valid base64');
+  const text = Buffer.from(encoded, 'base64').toString('utf8');
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+function parseBatch(response, requests, batchId) {
+  // ServiceNow's endpoint returns these arrays directly, not in a Table API
+  // result wrapper. Missing/duplicated correlations are never inferred by order.
+  if (!response || response.batch_request_id !== batchId || !Array.isArray(response.serviced_requests) || !Array.isArray(response.unserviced_requests)) {
+    throw malformed('expected matching batch_request_id and serviced/unserviced arrays');
+  }
+  const expected = new Set(requests.map(item => item.id));
+  const mapped = new Map();
+  for (const id of response.unserviced_requests) {
+    if (typeof id !== 'string' || !expected.has(id) || mapped.has(id)) throw malformed('unknown or duplicate unserviced ID');
+    mapped.set(id, { id, ok: false, serviced: false, status: null, data: null,
+      error: { code: 'batch_unserviced', message: 'The batch processing limit left this request unserviced; it was not retried.' } });
+  }
+  for (const item of response.serviced_requests) {
+    if (!item || !expected.has(item.id) || mapped.has(item.id)) throw malformed('unknown or duplicate serviced ID');
+    const status = item.status_code;
+    if (!Number.isInteger(status) || status < 100 || status > 599) throw malformed('invalid item HTTP status');
+    const ok = status >= 200 && status < 300;
+    let data;
+    try { data = decodeBody(item.body); } catch (error) {
+      mapped.set(item.id, { id: item.id, ok: false, serviced: true, status, data: null, error: errorData(error) });
+      continue;
+    }
+    const error = ok ? null : errorData(errAPI(status, typeof data === 'string' ? data : JSON.stringify(data || { error: item.error_message || item.status_text || 'Request failed' })));
+    mapped.set(item.id, { id: item.id, ok, serviced: true, status, data, error });
+  }
+  return requests.map(({ id }) => mapped.get(id) || { id, ok: false, serviced: null, status: null, data: null,
+    error: { code: 'batch_missing_response', message: 'No correlated response was returned; execution is unknown and was not retried.' } });
+}
+async function individual(sdk, request, timeout) {
+  try {
+    return await sdk._withAuthenticatedRequest(`${sdk.baseURL}${request.url}`, {
+      method: 'GET', headers: Object.fromEntries(request.headers.map(({ name, value }) => [name, value])),
+    }, { timeout, normalizeErrors: true }, async response => {
+      const text = await response.text();
+      let data = text || null;
+      if (text) { try { data = JSON.parse(text); } catch { /* Non-JSON REST reads remain text. */ } }
+      return { id: request.id, ok: response.ok, serviced: true, status: response.status, data,
+        error: response.ok ? null : errorData(errAPI(response.status, text)) };
+    });
+  } catch (error) {
+    return { id: request.id, ok: false, serviced: null, status: error.status || null, data: null, error: errorData(error) };
+  }
+}
+
+/**
+ * @param {SDKClient} sdk authenticated SDK instance
+ * @param {Array<{id?: string, method?: 'GET', url: string, headers?: object}>} requests
+ * @param {{fallback?: boolean, chunkSize?: number, timeout?: number}} options
+ */
+export async function batchRead(sdk, requests, { fallback = true, chunkSize = 50, timeout = sdk.timeout } = {}) {
+  if (typeof fallback !== 'boolean') throw errUsage('Batch fallback must be a boolean.');
+  const normalized = normalizeRequests(sdk, requests);
+  if (!Number.isInteger(chunkSize) || chunkSize < 1 || chunkSize > 1000) throw errUsage('Batch chunkSize must be an integer from 1 to 1000.');
+  const results = [], transports = new Set();
+  for (let offset = 0; offset < normalized.length; offset += chunkSize) {
+    const chunk = normalized.slice(offset, offset + chunkSize);
+    let useIndividual = fallback && sdk._batchUnsupported === true;
+    if (!useIndividual) {
+      const batchId = randomUUID();
+      try {
+        const response = await sdk.request(`${sdk.baseURL}/api/now/v1/batch`, {
+          method: 'POST', timeout, touchLastSeen: false,
+          body: JSON.stringify({ batch_request_id: batchId, rest_requests: chunk }),
+        });
+        results.push(...parseBatch(response, chunk, batchId));
+        transports.add('batch');
+      } catch (error) {
+        // Only explicit endpoint absence permits fallback. ACL/auth, rate limits,
+        // malformed responses and uncertain transport failures must not replay.
+        if (!fallback || !UNSUPPORTED.has(error.status)) throw error;
+        sdk._batchUnsupported = true;
+        useIndividual = true;
+      }
+    }
+    if (useIndividual) {
+      transports.add('individual');
+      for (const request of chunk) results.push(await individual(sdk, request, timeout));
+    }
+  }
+  const successful = results.filter(item => item.ok).length;
+  return { transport: transports.size > 1 ? 'mixed' : [...transports][0] || 'none',
+    results, counts: { total: results.length, successful, failed: results.length - successful } };
+}

package/src/sdk.js

@@ -1,5 +1,6 @@
 // ServiceNow REST API client
 
+import { batchRead } from './sdk-batch.js';
 import { gunzipSync } from 'node:zlib';
 import { CodeAuth, errAuth, errAPI, errNetwork } from './errors.js';
 import { getStringField } from './helpers.js';
@@ -48,6 +49,7 @@ export class SDKClient {
     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;
@@ -104,7 +106,47 @@ 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) {
     for (let attempt = 0; attempt < 2; attempt++) {
@@ -200,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);
   }