@jacebenson/jsn 4.1.0 → 4.2.0

package/src/resolve-record.js

@@ -0,0 +1,71 @@
+// Shared resolver for "find one record by a human identifier".
+//
+// Every command that accepts a number / name / user_name / sys_id used to
+// hand-roll the same five steps (classify the identifier, guard the query,
+// build params, fetch, unwrap sys_id) — and they drifted: hex detection
+// differed per file and some lookups forgot sysparm_display_value=all, so a
+// wrapped {value, display_value} sys_id leaked into update/delete calls.
+// This module is the single deep seam; commands shrink to
+// resolve → mutate → report.
+
+import { assertSafeExactMatch, isHexString } from './helpers.js';
+import { errNotFound } from './errors.js';
+
+/**
+ * True when the identifier looks like a ServiceNow sys_id (32 hex chars).
+ * Exported so call sites that only need classification share one definition.
+ */
+export function isSysId(identifier) {
+  return typeof identifier === 'string' && identifier.length === 32 && isHexString(identifier);
+}
+
+/**
+ * Unwrap a record's sys_id, which may be a plain string or a
+ * {value, display_value} object when display values were requested.
+ */
+export function unwrapSysId(record) {
+  const sysId = record?.sys_id;
+  if (sysId && typeof sysId === 'object') return sysId.value || sysId.display_value || '';
+  return sysId || '';
+}
+
+/**
+ * Resolve a single record by human identifier.
+ *
+ * @param {object} sdk — SDK handle (uses sdk.list)
+ * @param {object} opts
+ * @param {string} opts.table — ServiceNow table
+ * @param {string} opts.identifier — sys_id (32 hex) or value of matchField
+ * @param {string} opts.matchField — field to match non-sys_id identifiers on
+ *   (e.g. 'number', 'name', 'user_name')
+ * @param {string} [opts.resource] — label for the not-found error
+ *   (e.g. 'User' → "User not found: <id>"); defaults to matchField
+ * @param {string[]} [opts.fields] — restrict sysparm_fields when set
+ * @returns {Promise<object>} the record (display values requested)
+ * @throws {AppError} code not_found when no record matches
+ */
+export async function resolveRecord(sdk, { table, identifier, matchField, resource, fields }) {
+  assertSafeExactMatch(identifier);
+  const queryField = isSysId(identifier) ? 'sys_id' : matchField;
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `${queryField}=${identifier}`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_display_value', 'all');
+  if (fields && fields.length > 0) {
+    params.set('sysparm_fields', fields.join(','));
+  }
+  const records = await sdk.list(table, params);
+  if (records.length === 0) {
+    throw errNotFound(resource || matchField, identifier);
+  }
+  return records[0];
+}
+
+/**
+ * Resolve a record and return just its raw sys_id.
+ * Same options as resolveRecord; defaults to fetching only sys_id.
+ */
+export async function resolveSysId(sdk, opts) {
+  const record = await resolveRecord(sdk, { fields: ['sys_id'], ...opts });
+  return unwrapSysId(record);
+}

package/src/sdk.js

@@ -6,6 +6,23 @@ import { getStringField } from './helpers.js';
 
 const DEFAULT_TIMEOUT = 30000;
 
+// Build the sys.scripts.do POST body for background script execution.
+// Extracted for testability (issue #177): maps script-mode options to the
+// form fields on ServiceNow's Script Background form. Defaults preserve the
+// historical behavior (rollback recording on, quota-managed transaction on).
+export function buildScriptFormBody({ script, csrf, scope, rollback = true, quotaManagedTransaction = true, sandbox = false, scriptlet = false }) {
+  const formBody = new URLSearchParams();
+  formBody.set('script', script);
+  formBody.set('sysparm_ck', csrf);
+  formBody.set('runscript', 'Run script');
+  formBody.set('sys_scope', scope || 'global');
+  if (rollback) formBody.set('record_for_rollback', 'on');
+  if (quotaManagedTransaction) formBody.set('quota_managed_transaction', 'on');
+  if (sandbox) formBody.set('sandbox', 'on');
+  if (scriptlet) formBody.set('scriptlet', 'on');
+  return formBody;
+}
+
 export class SDKClient {
   constructor(baseURL, authProvider, opts = {}) {
     this.baseURL = baseURL.replace(/\/$/, '');
@@ -177,6 +194,55 @@ export class SDKClient {
     await this.request(endpoint, { method: 'DELETE' });
   }
 
+  // ─── Attachments ───
+
+  /**
+   * List attachments on a record.
+   * @param {string} sysID - record sys_id
+   * @returns {Promise<Array>} attachment metadata rows
+   */
+  async listAttachments(sysID) {
+    const params = new URLSearchParams();
+    params.set('sysparm_query', `table_sys_id=${sysID}`);
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', 'sys_id,file_name,size_bytes,content_type,sys_created_by,sys_created_on');
+    const endpoint = `${this.baseURL}/api/now/attachment?${params.toString()}`;
+    const result = await this.request(endpoint, { method: 'GET' });
+    return result?.result || [];
+  }
+
+  /**
+   * Download an attachment's file contents as a Buffer.
+   * @param {string} sysID - attachment sys_id
+   * @returns {Promise<Buffer>}
+   */
+  async getAttachment(sysID) {
+    const endpoint = `${this.baseURL}/api/now/attachment/${sysID}/file`;
+    const resp = await this._fetchWithAuth(endpoint, { method: 'GET', headers: { Accept: 'application/octet-stream' } });
+    if (!resp.ok) {
+      throw errAPI(resp.status, String(resp.statusText));
+    }
+    const buf = Buffer.from(await resp.arrayBuffer());
+    return buf;
+  }
+
+  /**
+   * Upload a file as a new attachment on a record.
+   * @param {string} table - parent table name (e.g. 'incident')
+   * @param {string} sysID - parent record sys_id
+   * @param {Buffer|string} content - file bytes or path
+   * @param {string} fileName - display file name
+   * @returns {Promise<object>} created attachment row
+   */
+  async addAttachment(table, sysID, content, fileName) {
+    const form = new FormData();
+    const blob = Buffer.isBuffer(content) ? new Blob([content]) : new Blob([String(content)]);
+    form.append('file', blob, fileName);
+    const endpoint = `${this.baseURL}/api/now/attachment?table_name=${encodeURIComponent(table)}&table_sys_id=${encodeURIComponent(sysID)}`;
+    const result = await this.request(endpoint, { method: 'POST', body: form });
+    return result?.result || null;
+  }
+
   async getCurrentUser() {
     const params = new URLSearchParams();
     params.set('sysparm_query', 'user_name=javascript:gs.getUserName()');
@@ -433,6 +499,31 @@ export class SDKClient {
 
   // ─── Background Script Execution (3-step OAuth session flow) ───
 
+  /**
+   * Export an update set to XML via the fluent export endpoint.
+   * Same session dance as executeScript: warm the session for cookies,
+   * grab the CSRF token from sys.scripts.do, then GET the export endpoint.
+   *
+   * @param {string} updateSetSysId - sys_id of the sys_update_set record
+   * @param {string} appSysId - sys_scope sys_id (scope of the update set)
+   * @returns {Promise<string>} The update set XML document
+   */
+  async exportUpdateSet(updateSetSysId, appSysId = '') {
+    const cookies = await this._warmSession();
+    const csrfToken = await this._getScriptsPageCSRF(cookies);
+
+    const params = new URLSearchParams();
+    params.set('sysparm_ck', csrfToken);
+    params.set('sysparm_sys_id', updateSetSysId);
+    params.set('sysparm_app_sys_id', appSysId);
+
+    const endpoint = `${this.baseURL}/fluent_update_set_export.do?${params.toString()}`;
+    return this.rawRequest(endpoint, {
+      method: 'GET',
+      headers: cookies ? { Cookie: cookies } : {},
+    });
+  }
+
   /**
    * Execute a background script on the ServiceNow instance via sys.scripts.do.
    * Uses a 3-step session-establishment flow compatible with OAuth tokens:
@@ -441,9 +532,16 @@ export class SDKClient {
    *  3. POST /sys.scripts.do with the script, CSRF token, and cookies
    *
    * @param {string} script - JavaScript code to execute
+   * @param {string} scope - Scope sys_id to run under ('' = global)
+   * @param {object} [opts] - Script-mode flags (issue #177), mapping to the
+   *   Script Background form checkboxes:
+   *   - rollback (default true) → record_for_rollback
+   *   - quotaManagedTransaction (default true) → quota_managed_transaction
+   *   - sandbox (default false) → sandbox (KittyScript, single expression)
+   *   - scriptlet (default false) → scriptlet
    * @returns {Promise<string>} The script's output text
    */
-  async executeScript(script, scope) {
+  async executeScript(script, scope, opts = {}) {
     // Step 1: Warm up the session by hitting any REST API — this makes
     // ServiceNow issue session cookies for subsequent UI page requests.
     // We capture cookies to forward them (Node.js fetch() has no built-in cookie jar).
@@ -454,13 +552,15 @@ export class SDKClient {
 
     // Step 3: POST the script with form data including the CSRF token.
     const endpoint = `${this.baseURL}/sys.scripts.do`;
-    const formBody = new URLSearchParams();
-    formBody.set('script', script);
-    formBody.set('sysparm_ck', csrfToken);
-    formBody.set('runscript', 'Run script');
-    formBody.set('sys_scope', scope || 'global');
-    formBody.set('record_for_rollback', 'on');
-    formBody.set('quota_managed_transaction', 'on');
+    const formBody = buildScriptFormBody({
+      script,
+      csrf: csrfToken,
+      scope,
+      rollback: opts.rollback,
+      quotaManagedTransaction: opts.quotaManagedTransaction,
+      sandbox: opts.sandbox,
+      scriptlet: opts.scriptlet,
+    });
 
     const html = await this.rawRequest(endpoint, {
       method: 'POST',

package/src/session.js

@@ -0,0 +1,214 @@
+// Session resolver — one module owns the answer to "which instance am I
+// talking to, as whom, with what profile flags?"
+//
+// Before this module existed, that composite answer was assembled across
+// four files with shared mutable state:
+//   - cli.js middleware resolved --profile by mutating cfg.activeProfile as
+//     a side effect, and poked BOTH app._overrideInstance and
+//     argv._overrideInstance (the --instance branch duplicated across two
+//     adjacent middlewares);
+//   - app.js carried _overrideInstance + getEffectiveInstance +
+//     setEffectiveInstance, re-deriving the active profile three ways;
+//   - auth.js reached into configProvider.config.profiles to re-derive the
+//     username for credential keying;
+//   - config.js's getEffectiveInstance duplicated the
+//     activeProfile || defaultProfile incantation.
+//
+// Now: resolveSession({argv-ish}, config) → a session object (pure — no
+// mutation of argv OR config), applySession(app, session) is the SINGLE
+// point where a flag override changes app/config state, and App keeps the
+// resolved session on app.session for anything that needs identity
+// (AuthManager is handed a provider over it, so it no longer spelunks
+// config internals).
+//
+// Precedence (pinned by test/session.test.js — preserve exactly):
+//   --instance flag > --profile reference > active profile >
+//   default profile > legacy bare instanceURL
+//
+// Deliberately NOT here: env var loading (loadConfig already folds
+// SERVICENOW_INSTANCE_URL into cfg.instanceURL before the resolver runs)
+// and credential storage I/O (auth.js owns the keyring/file stores).
+
+import { normalizeInstanceURL } from './config.js';
+import { extractProfileName } from './helpers.js';
+import { errUsage } from './errors.js';
+
+/**
+ * Resolve the composite session from parsed argv flags + loaded config.
+ * Pure: never mutates argv or config.
+ *
+ * @param {object} [argv] — anything with optional { instance, profile }
+ *   (a yargs argv, or a hand-built { instance, profile } shape)
+ * @param {object} config — the loaded config (from loadConfig())
+ * @returns {{
+ *   instance: string,        // effective instance URL ('' when unresolved)
+ *   profileName: string|null,// active profile name after flags
+ *   profile: object|null,    // the profile entry (instance_url, flags, ...)
+ *   username: string|null,   // profile username for credential keying
+ *   domain: string,          // domain-separation sys_id ('' = no scoping)
+ *   readOnly: boolean,       // profile.read_only === true (the armed guard)
+ *   override: string|null,   // normalized flag override URL, null when none
+ *   profileExplicit: boolean,// true when --profile named the active profile
+ *   unknownProfile: string|null, // set when --profile named no known profile
+ * }}
+ */
+export function resolveSession(argv = {}, config) {
+  const cfg = config || {};
+  const profiles = cfg.profiles || {};
+
+  // --profile selects the active profile for this run. Unknown names are
+  // surfaced as data (unknownProfile) — the caller (cli.js middleware)
+  // decides how to render the guard exit; resolving must not throw because
+  // App is constructed before argv exists.
+  let unknownProfile = null;
+  let profileName = null;
+  if (argv.profile) {
+    if (profiles[argv.profile]) {
+      profileName = argv.profile;
+    } else {
+      unknownProfile = argv.profile;
+    }
+  }
+  if (!profileName) {
+    const fallback = cfg.activeProfile || cfg.defaultProfile;
+    if (fallback && profiles[fallback]) profileName = fallback;
+  }
+
+  const profile = profileName ? profiles[profileName] : null;
+
+  // Instance: --instance flag > profile reference > active/default
+  // profile > legacy bare instanceURL. The override is normalized here so
+  // every downstream consumer (SDK client, context header links) sees the
+  // canonical form. --profile counts as an override too (the old code
+  // poked the profile's URL into app._overrideInstance and rebuilt the SDK
+  // via setEffectiveInstance's normalization) — session.instance is always
+  // the normalized effective URL either way.
+  let override = null;
+  if (argv.instance) {
+    override = normalizeInstanceURL(argv.instance) || null;
+  } else if (argv.profile && profile?.instance_url) {
+    override = normalizeInstanceURL(profile.instance_url) || null;
+  }
+
+  const instance = normalizeInstanceURL(override || (profile && profile.instance_url) || cfg.instanceURL || '');
+
+  return {
+    instance,
+    profileName,
+    profile,
+    username: (profile && profile.username) || null,
+    domain: (profile && profile.domain) || '',
+    readOnly: profile?.read_only === true,
+    override,
+    profileExplicit: Boolean(argv.profile) && !unknownProfile,
+    unknownProfile,
+  };
+}
+
+/**
+ * Derive the legacy context block (profileName + username for the context
+ * header) from a session. Kept separate from the session itself because
+ * printContextHeader() enriches it with live instance data (scope, update
+ * set) — the session stays a snapshot of resolution-time truth.
+ *
+ * Legacy fallback preserved: with no active profile NAME, find the profile
+ * whose instance_url matches the effective instance (legacy configs that
+ * predate named profiles), else derive a display name from the URL host.
+ */
+export function contextFromSession(session, config) {
+  const context = { profileName: '', username: '', scope: '', updateSet: '' };
+  if (!session) return context;
+
+  if (session.profileName) {
+    context.profileName = session.profileName;
+    context.username = session.username || '';
+    return context;
+  }
+
+  if (!session.instance) return context;
+  context.profileName = extractProfileName(session.instance);
+  for (const [name, profile] of Object.entries(config?.profiles || {})) {
+    if (profile.instance_url === session.instance) {
+      context.profileName = name;
+      context.username = profile.username || '';
+      break;
+    }
+  }
+  return context;
+}
+
+/**
+ * Apply a resolved session to the App — the ONLY place flag overrides
+ * change app/config state. Explicit, greppable, and called from exactly
+ * one middleware (cli.js). Replaces the old scattered trio:
+ *   cfg.activeProfile = argv.profile  (buried side effect)
+ *   app._overrideInstance = url; argv._overrideInstance = url  (mirrored)
+ *
+ * @param {import('./app.js').App} app
+ * @param {object} sessionOrArgv — a resolveSession() result, or a bare
+ *   { instance, profile } argv shape (resolved here for convenience)
+ * @returns {object} the applied session
+ */
+export function applySession(app, sessionOrArgv) {
+  // A resolved session carries `override` (null when no flag); bare argv
+  // ({ instance, profile }) does not. (Object.hasOwn, not `in` — plain
+  // objects inherit Object.prototype, which has neither, but hasOwn is the
+  // intent-precise check.)
+  const isResolved = sessionOrArgv != null && Object.hasOwn(sessionOrArgv, 'override');
+  const session = isResolved
+    ? sessionOrArgv
+    : resolveSession(sessionOrArgv, app.config);
+
+  // --profile: switch the active profile on the config so anything still
+  // reading config directly (legacy callers, help rendering) sees the same
+  // answer the session computed. Flag args are pinned on _sessionArgv so
+  // refreshSession() (after config edits) keeps the same flags in force.
+  if (session.profileExplicit) {
+    app.config.activeProfile = session.profileName;
+    app._sessionArgv = { ...(app._sessionArgv || {}), profile: session.profileName };
+  }
+  if (!isResolved && sessionOrArgv?.instance !== undefined) {
+    app._sessionArgv = { ...(app._sessionArgv || {}), instance: sessionOrArgv.instance };
+  }
+
+  // Flag overrides (--instance, --profile) pin the effective instance for
+  // this run and rebuild the SDK client against it. No flags → clear any
+  // stale override so the config-sourced instance is authoritative. (The
+  // SDK must be rebuilt even at the same URL: the domain scope comes from
+  // the newly-active profile.)
+  app._overrideInstance = session.override;
+  if (session.instance) {
+    app._buildSdk(session.instance, session);
+  } else {
+    app.sdk = null;
+  }
+
+  app.session = session;
+  app.loadContext();
+  return session;
+}
+
+/**
+ * Re-resolve the session after config edits (profile switched, created,
+ * or removed by auth/setup commands). Explicit flag overrides are pinned
+ * by re-resolving against the pinned argv; without them the config is
+ * authoritative.
+ *
+ * @param {import('./app.js').App} app
+ * @returns {object} the refreshed session
+ */
+export function refreshSession(app) {
+  return applySession(app, app._sessionArgv || {});
+}
+
+/**
+ * The missing-instance guard, backed by the session. The message and code
+ * (usage → exit 2 via the unified renderer) are observable behavior pinned
+ * by test/core.test.js — do not reword.
+ */
+export function requireSessionInstance(session) {
+  if (!session || !session.instance) {
+    throw errUsage('Instance URL required. Set via --instance flag, SERVICENOW_INSTANCE_URL env, or config file.');
+  }
+  return session.instance;
+}