@jacebenson/jsn 4.3.13-dev.80.1 → 4.3.13-dev.82.1

package/package.json

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

package/src/commands/forms.js

@@ -1,105 +1,29 @@
 import { getStringField, interactiveList } from '../helpers.js';
 
-function getDisplayValue(record, key) {
-  if (!record || typeof record !== 'object') return '';
-  const val = record[key];
-  if (val == null) return '';
-  if (typeof val === 'string') return val;
-  if (typeof val === 'object') {
-    if (val.display_value != null && val.display_value !== '') return String(val.display_value);
-    if (val.value != null) return String(val.value);
-  }
-  return String(val);
-}
-
-function getIntValue(record, key) {
-  if (!record || typeof record !== 'object') return 0;
-  const val = record[key];
-  if (val == null) return 0;
-  if (typeof val === 'number') return Math.floor(val);
-  if (typeof val === 'string') { const n = parseInt(val, 10); return isNaN(n) ? 0 : n; }
-  if (typeof val === 'object' && val.value != null) { const n = parseInt(val.value, 10); return isNaN(n) ? 0 : n; }
-  return 0;
-}
-
-async function showForm(app, table, viewName) {
-  // 1) Look up the view
-  const viewParams = new URLSearchParams();
-  viewParams.set('sysparm_limit', '1');
-  viewParams.set('sysparm_fields', 'sys_id');
-  viewParams.set('sysparm_display_value', 'all');
-  viewParams.set('sysparm_query', `name=${viewName}`);
-  let viewSysID = '';
-  try { const vr = await app.sdk.list('sys_ui_view', viewParams); if (vr.length > 0) viewSysID = getStringField(vr[0], 'sys_id'); } catch { /* ignore */ }
-  if (!viewSysID) {
-    viewParams.set('sysparm_query', `title=${viewName}`);
-    try { const vr = await app.sdk.list('sys_ui_view', viewParams); if (vr.length > 0) viewSysID = getStringField(vr[0], 'sys_id'); } catch { /* ignore */ }
-  }
-
-  // 2) Get sections for this table + view
-  const secParams = new URLSearchParams();
-  secParams.set('sysparm_limit', '200');
-  secParams.set('sysparm_fields', 'sys_id,caption');
-  secParams.set('sysparm_display_value', 'all');
-  secParams.set('sysparm_query', `name=${table}^view=${viewName}^ORDERBYposition`);
-  if (viewSysID) {
-    secParams.set('sysparm_query', `name=${table}^view=${viewSysID}^ORDERBYposition`);
-  }
-  const sections = await app.sdk.list('sys_ui_section', secParams);
-
-  // 3) Get elements for each section
-  const sectionsOut = [];
-  for (const sec of sections) {
-    const secSysID = getStringField(sec, 'sys_id');
-    const sectionCaption = getDisplayValue(sec, 'caption') || '(unnamed)';
+import { createRecordMetadataReader } from '../metadata/records.js';
 
-    let elements = [];
-    if (secSysID) {
-      const elemParams = new URLSearchParams();
-      elemParams.set('sysparm_limit', '500');
-      elemParams.set('sysparm_fields', 'element,type,label,position');
-      elemParams.set('sysparm_display_value', 'all');
-      elemParams.set('sysparm_query', `sys_ui_section=${secSysID}^ORDERBYposition`);
-      try { elements = await app.sdk.list('sys_ui_element', elemParams); } catch { /* ignore */ }
-    }
-
-    sectionsOut.push({
-      caption: sectionCaption,
-      position: getIntValue(sec, 'position'),
-      elements: elements
-        .map(e => ({
-          type: getDisplayValue(e, 'type'),
-          label: getDisplayValue(e, 'label'),
-          element: getDisplayValue(e, 'element'),
-          position: getIntValue(e, 'position'),
-        }))
-        .sort((a, b) => a.position - b.position),
-    });
+export function formatFormMetadata(metadata) {
+  const lines = [`Form: ${metadata.table} → ${metadata.requested_view}`];
+  if (metadata.form?.inherited) lines.push(`  Inherited layout: ${metadata.form.table}`);
+  if (!metadata.form) lines.push('  No unambiguous shared form layout is visible.');
+  for (const section of metadata.form?.sections || []) {
+    lines.push('', `── ${section.caption || '(unnamed)'} ──`);
+    for (const element of section.elements) lines.push(`  ${element.label || element.element || '(unnamed)'}${element.type ? ` (${element.type})` : ''}`);
+    if (!section.elements.length) lines.push('  (no visible elements)');
   }
-
-  sectionsOut.sort((a, b) => a.position - b.position);
-
-  // Build formatted output
-  const lines = [];
-  lines.push(`Form: ${table} → ${viewName}`);
-  if (viewSysID) lines.push(`  View: ${app.getEffectiveInstance()}/nav_to.do?uri=sys_ui_view.do?sys_id=${viewSysID}`);
-  lines.push('');
-
-  for (const sec of sectionsOut) {
-    const secLabel = sec.caption || '(unnamed)';
-    lines.push(`── ${secLabel} ──`);
-    if (sec.elements.length === 0) {
-      lines.push('  (no elements)');
-    }
-    for (const el of sec.elements) {
-      const elLabel = el.label || el.element || '(unnamed)';
-      const typeStr = el.type ? ` (${el.type})` : '';
-      lines.push(`  ${elLabel}${typeStr}`);
-    }
-    lines.push('');
+  const configured = metadata.related_lists.filter(item => item.configured);
+  if (configured.length) {
+    lines.push('', 'Configured related lists:');
+    for (const list of configured) lines.push(`  ${list.label || list.id} (${list.query_status})`);
   }
+  lines.push('', metadata.coverage.scope);
+  for (const warning of metadata.coverage.warnings) lines.push(`  ${warning.source}: ${warning.reason}`);
+  return lines.join('\n');
+}
 
-  process.stdout.write(lines.join('\n') + '\n');
+async function showForm(app, table, view) {
+  const metadata = await createRecordMetadataReader(app.sdk).read({ table, view });
+  app.ok({ ...metadata, _formatted: formatFormMetadata(metadata) }, { summary: `Form metadata for ${table}` });
 }
 
 export function formsCmd(wrap) {
@@ -164,7 +88,8 @@ export function formsCmd(wrap) {
           aliases: ['get'],
           describe: 'Show form layout',
           builder: (y) => y
-            .option('view', { type: 'string', default: 'Default view', describe: 'View name' }),
+            .option('view', { type: 'string', default: 'Default view', describe: 'Shared view name, title or sys_id' })
+            .epilogue('Discovers shared layouts, inherited forms and related-list metadata. JSON includes coverage limits; custom relationship scripts are never executed. Generic records get presentation is unchanged.'),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             await showForm(app, argv.table, argv.view);

package/src/metadata/records.js

@@ -0,0 +1,245 @@
+import { assertSafeExactMatch } from '../helpers.js';
+import { errUsage, errAuth } from '../errors.js';
+
+const namePattern = /^[a-zA-Z0-9_]+$/;
+const raw = value => String(value && typeof value === 'object' ? value.value ?? '' : value ?? '');
+const field = (record, name) => raw(record?.[name]);
+const position = row => Number(field(row, 'position')) || 0;
+const ordered = rows => [...rows].sort((a, b) => position(a) - position(b));
+const reference = value => {
+  const text = raw(value);
+  assertSafeExactMatch(text);
+  return text;
+};
+const isName = value => typeof value === 'string' && namePattern.test(value);
+const chunks = values => Array.from({ length: Math.ceil(values.length / 100) }, (_, index) => values.slice(index * 100, (index + 1) * 100));
+
+function request(table, query, fields, limit = 1000) {
+  return { table, params: new URLSearchParams({
+    sysparm_query: query, sysparm_fields: fields, sysparm_limit: String(limit),
+    sysparm_display_value: 'all', sysparm_exclude_reference_link: 'true',
+  }) };
+}
+
+/** Invocation-scoped, SDK-bound metadata reader. No persistence across users. */
+export function createRecordMetadataReader(sdk, { limit = 1000, maxDepth = 32 } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000) throw errUsage('Metadata limit must be an integer from 1 to 10000');
+  if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 100) throw errUsage('Metadata inheritance depth must be an integer from 1 to 100');
+  const cache = new Map();
+  const reports = new Map();
+
+  async function reads(specs, warnings) {
+    const missing = specs.filter(spec => !cache.has(`${spec.table}?${spec.params}`));
+    // Reserve promises before transport so concurrent metadata requests share
+    // both successful reads and observed failures within this reader only.
+    const unique = [...new Map(missing.map(spec => [`${spec.table}?${spec.params}`, spec])).values()];
+    if (unique.length) {
+      const pending = (async () => {
+        if (unique.length > 1 && typeof sdk.batch === 'function') {
+          try {
+            const batch = await sdk.batch(unique.map((spec, index) => ({
+              id: `metadata-${index}`, method: 'GET', url: `/api/now/table/${spec.table}?${spec.params}`,
+            })), { fallback: true });
+            return unique.map((spec, index) => {
+              const item = batch.results?.find(result => result.id === `metadata-${index}`);
+              if (item?.status === 401) throw errAuth('Authentication failed while reading metadata');
+              if (!item?.ok) return { rows: [], error: item?.error?.message || `Metadata read failed (${item?.status || 'unknown status'})` };
+              return normalize(item.data?.result, spec);
+            });
+          } catch (error) {
+            if (error.code === 'auth_error' || error.status === 401) throw error;
+            // The batch provider owns unsupported-endpoint fallback. Never
+            // replay authentication/ACL/server failures through another path.
+            return unique.map(() => ({ rows: [], error: error.message || 'Metadata batch failed' }));
+          }
+        }
+        return Promise.all(unique.map(async spec => {
+          try { return normalize(await sdk.list(spec.table, spec.params), spec); }
+          catch (error) {
+            if (error.code === 'auth_error' || error.status === 401) throw error;
+            return { rows: [], error: error.message || 'Metadata read failed' };
+          }
+        }));
+      })();
+      unique.forEach((spec, index) => cache.set(`${spec.table}?${spec.params}`, pending.then(results => results[index])));
+    }
+    return Promise.all(specs.map(async spec => {
+      const result = await cache.get(`${spec.table}?${spec.params}`);
+      if (result.error) warnings.push({ source: spec.table, reason: result.error });
+      if (result.truncated) warnings.push({ source: spec.table, reason: `Metadata limit ${spec.params.get('sysparm_limit')} reached; results may be incomplete` });
+      return result.rows;
+    }));
+  }
+
+  function normalize(rows, spec) {
+    if (!Array.isArray(rows)) return { rows: [], error: 'Metadata response was not an array' };
+    return { rows, truncated: rows.length >= Number(spec.params.get('sysparm_limit')) };
+  }
+
+  async function read({ table, view = 'Default view' }) {
+    if (!isName(table)) throw errUsage('Metadata table must be a table name containing letters, numbers or underscores');
+    if (typeof view !== 'string' || !view) throw errUsage('Metadata view must be a nonempty name, title or sys_id');
+    assertSafeExactMatch(view);
+    const key = `${table}\0${view}`;
+    if (!reports.has(key)) reports.set(key, load(table, view));
+    // Protect cached objects from a consumer attaching record-specific hints.
+    return structuredClone(await reports.get(key));
+  }
+
+  async function load(table, view) {
+    const warnings = [];
+    const hierarchy = [];
+    const visited = new Set();
+    let next = request('sys_db_object', `name=${table}`, 'sys_id,name,super_class', 2);
+    for (let depth = 0; next && depth < maxDepth; depth++) {
+      const [rows] = await reads([next], warnings);
+      if (rows.length !== 1) {
+        warnings.push({ source: 'sys_db_object', reason: `Expected one visible table definition, found ${rows.length}; inheritance coverage is incomplete` });
+        break;
+      }
+      const row = rows[0];
+      const name = field(row, 'name');
+      const id = field(row, 'sys_id');
+      if (!isName(name) || visited.has(name)) {
+        warnings.push({ source: 'sys_db_object', reason: 'Invalid or cyclic table inheritance metadata' });
+        break;
+      }
+      visited.add(name);
+      hierarchy.push({ name, sys_id: id });
+      if (!Object.hasOwn(row, 'super_class')) warnings.push({ source: 'sys_db_object', reason: 'Parent metadata is not visible; inheritance coverage is incomplete' });
+      const parent = reference(row.super_class);
+      next = parent ? request('sys_db_object', `sys_id=${parent}`, 'sys_id,name,super_class', 2) : null;
+    }
+    if (next && hierarchy.length === maxDepth) warnings.push({ source: 'sys_db_object', reason: `Inheritance depth limit ${maxDepth} reached` });
+    if (!hierarchy.length) hierarchy.push({ name: table, sys_id: '' });
+    const names = hierarchy.map(item => item.name);
+    const defaultView = view === 'Default view' || view === 'default';
+    const viewQuery = defaultView ? 'name=^ORname=default^ORtitle=Default view' : `name=${view}^ORtitle=${view}^ORsys_id=${view}`;
+    const [views] = await reads([request('sys_ui_view', `${viewQuery}^userISEMPTY`, 'sys_id,name,title', limit)], warnings);
+    const byId = views.filter(row => field(row, 'sys_id') === view);
+    const byName = views.filter(row => field(row, 'name') === (defaultView ? '' : view));
+    const byTitle = views.filter(row => field(row, 'title') === view);
+    const byAlias = defaultView ? views.filter(row => field(row, 'name') === 'default') : [];
+    const candidates = byId.length ? byId : byName.length ? byName : byTitle.length ? byTitle : byAlias;
+    let viewId = '';
+    const viewCapped = views.length >= limit;
+    if (candidates.length === 1 && !viewCapped) {
+      viewId = reference(candidates[0].sys_id);
+      if (!viewId) warnings.push({ source: 'sys_ui_view', reason: 'View id is absent or not visible' });
+    } else if (candidates.length > 1 || viewCapped) warnings.push({ source: 'sys_ui_view', reason: 'View lookup is ambiguous or capped; no layout was selected' });
+    else if (!defaultView) warnings.push({ source: 'sys_ui_view', reason: 'Requested view is absent or not visible; no layout was selected' });
+    const canReadLayout = !viewCapped && candidates.length <= 1 && (defaultView || !!viewId);
+    const viewFilter = viewId ? `view=${viewId}${defaultView ? '^ORviewISEMPTY' : ''}` : 'viewISEMPTY';
+    const specs = [
+      request('sys_dictionary', `referenceIN${names.join(',')}^elementISNOTEMPTY`, 'sys_id,name,element,reference,column_label', limit),
+      request('sys_relationship', `basic_apply_toIN${names.join(',')}`, 'sys_id,name,basic_apply_to,basic_query_from,reference_field,simple_reference,advanced,query_with', limit),
+      ...(canReadLayout ? [
+        request('sys_ui_form', `nameIN${names.join(',')}^${viewFilter}^sys_userISEMPTY`, 'sys_id,name,view', limit),
+        request('sys_ui_related_list', `nameIN${names.join(',')}^${viewFilter}^sys_userISEMPTY`, 'sys_id,name,view', limit),
+      ] : []),
+    ];
+    const [dictionary, relationships, forms = [], containers = []] = await reads(specs, warnings);
+    const nearest = rows => {
+      for (const name of names) {
+        const candidates = rows.filter(row => field(row, 'name') === name);
+        const exact = viewId ? candidates.filter(row => field(row, 'view') === viewId) : [];
+        const preferred = exact.length ? exact : candidates;
+        if (preferred.length > 1) warnings.push({ source: 'layout', reason: `Ambiguous layout for ${name}; no layout was selected` });
+        if (preferred.length) {
+          if (!field(preferred[0], 'sys_id')) {
+            warnings.push({ source: 'layout', reason: `Layout id is absent or not visible for ${name}` });
+            return null;
+          }
+          return preferred.length === 1 ? preferred[0] : null;
+        }
+      }
+      return null;
+    };
+    const form = nearest(forms);
+    const container = nearest(containers);
+    const detailSpecs = [
+      ...(form ? [request('sys_ui_form_section', `sys_ui_form=${reference(form.sys_id)}^ORDERBYposition`, 'sys_id,sys_ui_form,sys_ui_section,position', limit)] : []),
+      ...(container ? [request('sys_ui_related_list_entry', `list_id=${reference(container.sys_id)}^ORDERBYposition`, 'sys_id,related_list,position,filter,order_by', limit)] : []),
+    ];
+    const details = await reads(detailSpecs, warnings);
+    const links = form ? details.shift() : [];
+    const entries = container ? details.shift() : [];
+    const sectionIds = [...new Set(links.map(link => reference(link.sys_ui_section)).filter(Boolean))];
+    const relationshipIds = entries.map(entry => field(entry, 'related_list')).filter(value => /^REL:[a-f0-9]{32}$/i.test(value)).map(value => value.slice(4));
+    const missingRelationships = relationshipIds.filter(id => !relationships.some(row => field(row, 'sys_id') === id));
+    const tailSpecs = [
+      ...chunks(sectionIds).flatMap(ids => [
+        { ...request('sys_ui_section', `sys_idIN${ids.join(',')}^sys_userISEMPTY`, 'sys_id,name,caption,header,title,view', limit), group: 'sections' },
+        { ...request('sys_ui_element', `sys_ui_sectionIN${ids.join(',')}^sys_userISEMPTY^ORDERBYposition`, 'sys_id,sys_ui_section,element,type,position', limit), group: 'elements' },
+      ]),
+      ...chunks([...new Set(missingRelationships)]).map(ids => ({
+        ...request('sys_relationship', `sys_idIN${ids.join(',')}`, 'sys_id,name,basic_apply_to,basic_query_from,reference_field,simple_reference,advanced,query_with', limit), group: 'relationships',
+      })),
+    ];
+    const tail = await reads(tailSpecs, warnings);
+    const group = name => tail.flatMap((rows, index) => tailSpecs[index].group === name ? rows : []);
+    const sections = group('sections');
+    const elements = group('elements');
+    relationships.push(...group('relationships'));
+    const sectionsOut = ordered(links).map(link => {
+      const id = field(link, 'sys_ui_section');
+      const section = sections.find(row => field(row, 'sys_id') === id);
+      if (!section) warnings.push({ source: 'sys_ui_section', reason: `A linked section is absent or not visible` });
+      return { sys_id: id, caption: field(section, 'caption'), position: position(link),
+        elements: ordered(elements.filter(row => field(row, 'sys_ui_section') === id)).map(row => ({
+          element: field(row, 'element'), type: field(row, 'type'), label: field(row, 'label'), position: position(row),
+        })) };
+    });
+    const relatedLists = buildRelationships({ entries, dictionary, relationships, sourceTable: container ? field(container, 'name') : '', names, warnings });
+    return {
+      table, requested_view: view, view_sys_id: viewId, hierarchy,
+      form: form ? { sys_id: field(form, 'sys_id'), table: field(form, 'name'), inherited: field(form, 'name') !== table, sections: sectionsOut } : null,
+      related_lists: relatedLists,
+      coverage: { state: warnings.length ? 'partial' : 'observed', scope: 'Visible shared layout metadata only; ACLs, personalization and advanced relationships may hide or change runtime results', warnings },
+    };
+  }
+
+  return { read, clear() { cache.clear(); reports.clear(); } };
+}
+
+function buildRelationships({ entries, dictionary, relationships, sourceTable, names, warnings }) {
+  const result = new Map();
+  for (const row of dictionary) {
+    const table = field(row, 'name');
+    const referenceField = field(row, 'element');
+    if (!isName(table) || !isName(referenceField)) {
+      warnings.push({ source: 'sys_dictionary', reason: 'Ignored an invalid reference definition' });
+      continue;
+    }
+    if (!names.includes(field(row, 'reference'))) warnings.push({ source: 'sys_dictionary', reason: 'A reference target is absent, unrelated, or not visible' });
+    const id = `${table}.${referenceField}`;
+    result.set(id, { id, kind: 'reference', table, reference_field: referenceField,
+      references: field(row, 'reference'), label: field(row, 'column_label'), configured: false,
+      query_status: names.includes(field(row, 'reference')) ? 'reference' : 'unavailable' });
+  }
+  for (const row of relationships) {
+    const id = `REL:${field(row, 'sys_id')}`;
+    if (!/^REL:[a-f0-9]{32}$/i.test(id)) continue;
+    const table = field(row, 'basic_query_from');
+    const referenceField = field(row, 'reference_field');
+    const queryable = field(row, 'advanced') !== 'true' && field(row, 'advanced') !== '1'
+      && names.includes(field(row, 'basic_apply_to'))
+      && ['true', '1'].includes(field(row, 'simple_reference')) && !field(row, 'query_with').trim()
+      && isName(table) && isName(referenceField);
+    result.set(id, { id, kind: 'relationship', relationship_sys_id: field(row, 'sys_id'),
+      table: isName(table) ? table : '', reference_field: queryable ? referenceField : '',
+      label: field(row, 'name'), configured: false, query_status: queryable ? 'reference' : 'platform_required',
+      ...(queryable ? {} : { reason: 'Custom/advanced relationship requires platform query logic; scripts are never executed by metadata discovery' }),
+    });
+  }
+  for (const entry of ordered(entries)) {
+    const id = field(entry, 'related_list');
+    const existing = result.get(id);
+    const descriptor = existing || { id, kind: 'unresolved', table: '', reference_field: '', query_status: 'unavailable',
+      reason: 'Configured related list metadata is absent, unsupported, or not visible' };
+    result.set(id, { ...descriptor, configured: true, source_table: sourceTable, position: position(entry),
+      filter: field(entry, 'filter'), order_by: field(entry, 'order_by') });
+    if (!existing) warnings.push({ source: 'sys_ui_related_list_entry', reason: descriptor.reason });
+  }
+  return [...result.values()].sort((a, b) => Number(b.configured) - Number(a.configured) || (a.position || 0) - (b.position || 0));
+}

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';
@@ -241,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);
   }